pympc
=====
Perform checks for the presence of minor bodies at astronomical locations for a given epoch.
## Installation
`pip install pympc`
or download/clone source and:
`python setup.py install`
## Setup
First we need to import the package and grab the orbit element catalogue. This must be done at least
once prior to any searches and can be run to overwrite the catalogues with the latest versions.
The default call signature is shown.
```python
import pympc
xephem_cat =pympc.update_catalogue()
print(xephem_cat)
# e.g. /tmp/mpcorb_xephem.csv
```
The catalogue downloaded will be the [`mpcorb`](https://www.minorplanetcenter.net/data) catalogue
from the Minor Planet Center.
The Near Earth Asteroid and Comets catalogues will be downloaded and used to update the `mpcorb` entries based on
the values of the `include_nea` and `include_comets` arguments (both default to `True`).
It will create a csv file for each catalogue downloaded in the
[xephem database format](http://www.clearskyinstitute.com/xephem/help/xephem.html#mozTocId468501) and return
the filepath to this file. By default the file will be saved in the user's temporary directory - this can
be changed by setting the `cat_dir` argument.
## Usage
Having downloaded the catalogue (see [Setup](#Setup)), we can now search for minor bodies at a given location.
### Interactive searching
> **Note:** All information is output in logging. If you do not have a lgger set up in a session, running:
> ```python
> import logging
> logging.getLogger().setLevel(logging.INFO)
> ```
> prior to the examples will show this information.
Within an interpretor session, define a search location, epoch and radius and run the search.
```python
import astropy.units as u
import pympc
from astropy.time import Time
ra = 230.028 * u.deg
dec = -11.774 * u.deg
epoch = Time("2019-01-01T00:00")
search_radius = 5 * u.arcmin
observatory = 950 # observatory code for La Palma
pympc.minor_planet_check(ra, dec, epoch, search_radius, observatory=observatory)
```
Results are returned as an astropy table.
The above example uses explicit quantities, but if passed simple float arguments, and the program will assume the
units (see comments below and `pympc.minor_planet_check()` docstring for unit assumptions).
```python
import pympc
ra = 230.028 # assumed degrees
dec = -11.774 # assumed degrees
epoch = 58484. # assumed MJD
search_radius = 30 # assumed arcseconds
observatory = 950 # observatory code for La Palma
pympc.minor_planet_check(ra, dec, epoch, search_radius, observatory=observatory)
```
By default, the search will use a default filepath for the catalogue. if the file has been moved - or a
custom `cat_dir` was passed to `pympc.update_catalogue()` - then the filepath can be specified.
```python
import pympc
pympc.minor_planet_check(ra=230.028, dec=-11.774, epoch=58484., search_radius=30, xephem_filepath='/path/to/mpcorb_xphem.csv')
```
### Defining an observer
By default, if the `observatory` argument is not passed, the program will return geocentric coordinates. However, for
relatively nearby objects like minor bodies, there can be signicant parallax introduced by the location of an observer
on the Earth's surface. For this reason it is crucial to pass either an
[observatory code](https://www.minorplanetcenter.net/iau/lists/ObsCodes.html) or a tuple containing the observatory
information. See the documentation for `pympc.minor_planet_check()` for more details.
## Speed and multiprocessing
The check should take of order a second or two, depending on multiprocessing capabilities.
The private function which actually performs the calculation is `_minor_planet_check()` (note leading underscore).
This can be called directly, to avoid the overhead associated with converting input arguments in `minor_planet_check()`,
if you provide them directly as required (see `_minor_planet_check()` docstring). Note that in this case a list of
tuples is returned, rather than an astropy table.
By default the program will calculate positions of bodies in the catalogue multiprocessed. To switch this off set
`chunk_size = 0`, i.e.:
```python
import pympc
pympc.minor_planet_check(ra=230.028, dec=-11.774, epoch=58484., search_radius=30, chunk_size=0)
```
### Console script searching
Installation of the package will create a `minor_planet_check` script, which can be accessed
from the command line. The options follow the same as the interactive searching, and results
are displayed as a table. For help on the command line use:
```bash
minor_planet_check --help
```
> It is not currently possible to pass a custom set of observatory coordinates to the script -
> an existing observatory code must be passed.
## Limitations
1. The orbits are propagated following [xephem](http://www.clearskyinstitute.com/xephem) (via the
[pyephem](https://rhodesmill.org/pyephem/) package), and this does not account for perturbations of the orbits. Thus,
the accuracy of the position is dependent on the time difference between the epoch of the orbit elements and the epoch
at which the search is being performed. Epoch differences between orbital elements calculation and observation of
a few months or less will provide typical positional accuracies of less than a few arcsecond for the vast
majority of minor bodies. Note, however, that a small number of bodies (those undergoing strong perturbations and
close to Earth) may be quite inaccurate (arcminutes). A fuller analysis is given in
[notebooks/positional_accuracy.ipynb](notebooks/positional_accuracy.ipynb), with the following histogram showing the results.
2. The `xephem` package can only provide geocentric astrometric positions. `pympc` will calculate the topocentric
correction as a post-processing to the initial position. The simple topometric correction applied is more than sufficient
for the overwhelming majority of minor bodies, but for some near earth objects the correction can be large and the
relatively simple treatment by `pympc` may not be sufficient. Additionally, in order to find matches in geocentric
positions prior to applying the topocentric correction, a buffer is added to the search radius - this should capture
the vast majority of cases where the geocentric position is outside the seach radius but the topocentric position is
within it - unless the object is within ~1/3 AU of Earth. To work around this you can artifically inflate your
search radius and filter yourself afterwards.
3. The filtering of matches based on magnitude via `max_mag` argument to `minor_planet_check()` is limited by the accuracy
of the magnitude information in the database so some buffer should be applied to the desired magnitude cutoff to allow
for this.
### Acknowledgements
This package makes use of data and/or services provided by the International Astronomical Union's
[Minor Planet Center](https://www.minorplanetcenter.net).
Orbit elements are also sourced from [Lowell Observatory](https://asteroid.lowell.edu/main/), which is funded by the
Lowell Observatory Endowment and NASA PDART grant NNX16AG52G.
Based from a package developed by Chris Klein and Duncan Galloway.
Raw data
{
"_id": null,
"home_page": "https://github.com/lyalpha/pympc",
"name": "pympc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Joe Lyman",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b1/e3/16cbe8fae7efdcd17c1ac4ad36200e49606f6f4675d9b890b7c2c90e8563/pympc-1.2.2.tar.gz",
"platform": null,
"description": "pympc\n=====\n\nPerform checks for the presence of minor bodies at astronomical locations for a given epoch.\n\n## Installation\n\n`pip install pympc`\n\nor download/clone source and:\n\n`python setup.py install`\n\n## Setup\n\nFirst we need to import the package and grab the orbit element catalogue. This must be done at least \nonce prior to any searches and can be run to overwrite the catalogues with the latest versions. \nThe default call signature is shown.\n```python\nimport pympc\nxephem_cat =pympc.update_catalogue()\nprint(xephem_cat)\n# e.g. /tmp/mpcorb_xephem.csv\n```\n\nThe catalogue downloaded will be the [`mpcorb`](https://www.minorplanetcenter.net/data) catalogue \nfrom the Minor Planet Center.\n\nThe Near Earth Asteroid and Comets catalogues will be downloaded and used to update the `mpcorb` entries based on \nthe values of the `include_nea` and `include_comets` arguments (both default to `True`).\n \nIt will create a csv file for each catalogue downloaded in the \n[xephem database format](http://www.clearskyinstitute.com/xephem/help/xephem.html#mozTocId468501) and return\nthe filepath to this file. By default the file will be saved in the user's temporary directory - this can\nbe changed by setting the `cat_dir` argument.\n\n\n## Usage \n\nHaving downloaded the catalogue (see [Setup](#Setup)), we can now search for minor bodies at a given location.\n\n### Interactive searching\n\n> **Note:** All information is output in logging. If you do not have a lgger set up in a session, running:\n> ```python\n> import logging\n> logging.getLogger().setLevel(logging.INFO)\n> ```\n> prior to the examples will show this information.\n\nWithin an interpretor session, define a search location, epoch and radius and run the search.\n\n```python\nimport astropy.units as u\nimport pympc\nfrom astropy.time import Time\n\nra = 230.028 * u.deg\ndec = -11.774 * u.deg\nepoch = Time(\"2019-01-01T00:00\")\nsearch_radius = 5 * u.arcmin\nobservatory = 950 # observatory code for La Palma\npympc.minor_planet_check(ra, dec, epoch, search_radius, observatory=observatory)\n```\n\nResults are returned as an astropy table.\n\nThe above example uses explicit quantities, but if passed simple float arguments, and the program will assume the \nunits (see comments below and `pympc.minor_planet_check()` docstring for unit assumptions).\n```python\nimport pympc\nra = 230.028 # assumed degrees\ndec = -11.774 # assumed degrees\nepoch = 58484. # assumed MJD\nsearch_radius = 30 # assumed arcseconds\nobservatory = 950 # observatory code for La Palma\npympc.minor_planet_check(ra, dec, epoch, search_radius, observatory=observatory)\n```\n\nBy default, the search will use a default filepath for the catalogue. if the file has been moved - or a \ncustom `cat_dir` was passed to `pympc.update_catalogue()` - then the filepath can be specified.\n\n```python\nimport pympc\npympc.minor_planet_check(ra=230.028, dec=-11.774, epoch=58484., search_radius=30, xephem_filepath='/path/to/mpcorb_xphem.csv')\n```\n\n### Defining an observer\n\nBy default, if the `observatory` argument is not passed, the program will return geocentric coordinates. However, for\nrelatively nearby objects like minor bodies, there can be signicant parallax introduced by the location of an observer\non the Earth's surface. For this reason it is crucial to pass either an \n[observatory code](https://www.minorplanetcenter.net/iau/lists/ObsCodes.html) or a tuple containing the observatory\ninformation. See the documentation for `pympc.minor_planet_check()` for more details.\n\n## Speed and multiprocessing\nThe check should take of order a second or two, depending on multiprocessing capabilities.\n\nThe private function which actually performs the calculation is `_minor_planet_check()` (note leading underscore).\nThis can be called directly, to avoid the overhead associated with converting input arguments in `minor_planet_check()`,\nif you provide them directly as required (see `_minor_planet_check()` docstring). Note that in this case a list of \ntuples is returned, rather than an astropy table.\n\nBy default the program will calculate positions of bodies in the catalogue multiprocessed. To switch this off set\n`chunk_size = 0`, i.e.:\n\n```python\nimport pympc\npympc.minor_planet_check(ra=230.028, dec=-11.774, epoch=58484., search_radius=30, chunk_size=0)\n```\n\n### Console script searching\n\nInstallation of the package will create a `minor_planet_check` script, which can be accessed\nfrom the command line. The options follow the same as the interactive searching, and results\nare displayed as a table. For help on the command line use:\n```bash\nminor_planet_check --help\n```\n\n> It is not currently possible to pass a custom set of observatory coordinates to the script - \n> an existing observatory code must be passed.\n\n## Limitations\n\n1. The orbits are propagated following [xephem](http://www.clearskyinstitute.com/xephem) (via the \n[pyephem](https://rhodesmill.org/pyephem/) package), and this does not account for perturbations of the orbits. Thus, \nthe accuracy of the position is dependent on the time difference between the epoch of the orbit elements and the epoch \nat which the search is being performed. Epoch differences between orbital elements calculation and observation of \na few months or less will provide typical positional accuracies of less than a few arcsecond for the vast\nmajority of minor bodies. Note, however, that a small number of bodies (those undergoing strong perturbations and\nclose to Earth) may be quite inaccurate (arcminutes). A fuller analysis is given in \n[notebooks/positional_accuracy.ipynb](notebooks/positional_accuracy.ipynb), with the following histogram showing the results.\n\n![histogram showing positional accuracy of pympc vs minor planet center](/notebooks/position_accuracy.png \"Histogram showing positional accuracy of `pympc` vs Minor Planet Center\")\n\n2. The `xephem` package can only provide geocentric astrometric positions. `pympc` will calculate the topocentric \ncorrection as a post-processing to the initial position. The simple topometric correction applied is more than sufficient\nfor the overwhelming majority of minor bodies, but for some near earth objects the correction can be large and the \nrelatively simple treatment by `pympc` may not be sufficient. Additionally, in order to find matches in geocentric\npositions prior to applying the topocentric correction, a buffer is added to the search radius - this should capture\nthe vast majority of cases where the geocentric position is outside the seach radius but the topocentric position is \nwithin it - unless the object is within ~1/3 AU of Earth. To work around this you can artifically inflate your \nsearch radius and filter yourself afterwards.\n\n3. The filtering of matches based on magnitude via `max_mag` argument to `minor_planet_check()` is limited by the accuracy \nof the magnitude information in the database so some buffer should be applied to the desired magnitude cutoff to allow \nfor this.\n\n### Acknowledgements\nThis package makes use of data and/or services provided by the International Astronomical Union's \n[Minor Planet Center](https://www.minorplanetcenter.net).\n\nOrbit elements are also sourced from [Lowell Observatory](https://asteroid.lowell.edu/main/), which is funded by the \nLowell Observatory Endowment and NASA PDART grant NNX16AG52G.\n\nBased from a package developed by Chris Klein and Duncan Galloway.\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "minor planet checking",
"version": "1.2.2",
"project_urls": {
"Homepage": "https://github.com/lyalpha/pympc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b1e316cbe8fae7efdcd17c1ac4ad36200e49606f6f4675d9b890b7c2c90e8563",
"md5": "9b150bbce7c7f0a4997373ff1d0e2827",
"sha256": "e7a00a518c8d69c7e39f2a206f2d0a0dc361cd00d951079a35af314531c94390"
},
"downloads": -1,
"filename": "pympc-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "9b150bbce7c7f0a4997373ff1d0e2827",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 76841,
"upload_time": "2024-08-28T19:28:32",
"upload_time_iso_8601": "2024-08-28T19:28:32.104795Z",
"url": "https://files.pythonhosted.org/packages/b1/e3/16cbe8fae7efdcd17c1ac4ad36200e49606f6f4675d9b890b7c2c90e8563/pympc-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-28 19:28:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lyalpha",
"github_project": "pympc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pympc"
}
JSON
