transientNamer ∞

Python API for reading and caching TNS reports.

Documentation for transientNamer is hosted by Read the Docs (development version and master version). The code lives on github. Please report any issues you find here.

Features ∞

How to cite transientNamer ∞

If you use transientNamer in your work, please cite using the following BibTeX entry:

@software{Young_transientNamer,
    author = {Young, David R.},
    doi = {10.5281/zenodo.7970680},
    license = {GPL-3.0-only},
    title = ,
    url = {https://github.com/thespacedoctor/transientNamer}
}

Installation ∞

The easiest way to install transientNamer is to use pip (here we show the install inside of a conda environment):

conda create -n transientNamer python=3.7 pip
conda activate transientNamer
pip install transientNamer

Or you can clone the github repo and install from a local version of the code:

git clone git@github.com:thespacedoctor/transientNamer.git
cd transientNamer
python setup.py install

To upgrade to the latest version of transientNamer use the command:

pip install transientNamer --upgrade

To check installation was successful run transientNamer -v. This should return the version number of the install.

MySQL ∞

If you wish to make use of the tools that allow interaction with a MySQL database you have to have MySQL/Maria DB server installed and access to a database. Credentials to the database are to be added to the settings file (see initialisation).

You also need to install PyMySQL into your conda environment via:

conda install pymysql

Development ∞

If you want to tinker with the code, then install in development mode. This means you can modify the code from your cloned repo:

git clone git@github.com:thespacedoctor/transientNamer.git
cd transientNamer
python setup.py develop

Pull requests are welcomed!

Initialisation ∞

Before using transientNamer you need to use the init command to generate a user settings file. Running the following creates a yaml settings file in your home folder under ~/.config/transientNamer/transientNamer.yaml:

transientNamer init

The file is initially populated with transientNamer’s default settings which can be adjusted to your preference.

If at any point the user settings file becomes corrupted or you just want to start afresh, simply trash the transientNamer.yaml file and rerun transientNamer init.

Modifying the Settings ∞

Once created, open the settings file in any text editor and make any modifications needed. For example:

database settings:
    db: myDB
    host: localhost
    user: dbuser
    password: dbpass

astronote-cache: ~/Desktop/astronotes

# FIND IN YOUR USER ACCOUNT SETTING ON TNS : https://www.wis-tns.org
user-agent: 'tns_marker{"XXXX"}'

You will need to register to the TNS to get a unique tns-marker from your account settings on https://www.wis-tns.org. Once you have the tns-marker add it to your settings file.

Basic Python Setup ∞

If you plan to use transientNamer in your own scripts you will first need to parse your settings file and set up logging etc. One quick way to do this is to use the fundamentals package to give you a logger, a settings dictionary and a database connection (if connection details given in settings file):

## SOME BASIC SETUP FOR LOGGING, SETTINGS ETC
from fundamentals import tools
from os.path import expanduser
home = expanduser("~")
settingsFile  = home + "/.config/transientNamer/transientNamer.yaml"
su = tools(
    arguments={"settingsFile": settingsFile},
    docString=__doc__,
)
arguments, settings, log, dbConn = su.setup()

Caching and Parsing Astronotes ∞

Before parsing the Astronote contents it’s necessary to download the notes into a local cache to avoid redownloading every time you wish to parse them and (reduces strain placed on the TNS). Before you begin make sure you have set up the astronote-cache setting in the settings file (see initalisation instructions).

In the spirit of fair-usage the downloader will pause for 1 second in-between each individual note download.

From the Command-Line ∞

To cache the notes run the command:

transientNamer notes <reportedInLastDays>

So to cache notes from the last 10 days run transientNamer notes 10.

To also parse and import the cached notes into 3 MySQL database tables (astronotes_content, astronotes_keywords, astronotes_transients) run the same command but with the --import flag:

transientNamer --import notes <reportedInLastDays>

This will cause all unseen notes in the cache directory to be parsed and added to the database.

From Python Script ∞

To download the notes from the last 30 days use the following snippet.

from transientNamer import astronotes
an = astronotes(
    log=log,
    dbConn=dbConn,
    settings=settings
)
downloadCount = an.download(
    cache_dir=settings["astronote-cache"], inLastDays=30)
print(f"{downloadCount} new astronotes downloaded and cached")

And to then parse the notes to the database tables add:

an.notes_to_database()

Todo List ∞

Todo

nice!

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/transientnamer/checkouts/master/docs/source/_template_.md, line 1.)

Release Notes ∞

v0.4.6 - July 3, 2023

FIXED: small fixes to unit-tests

v0.4.5 - January 10, 2023

FIXED: changes to search url to reflectv changes made on the TNS. All transients should now be reported again.

v0.4.4 - June 17, 2022

FIXED: unit-tests failing due to throttling from TNS

v0.4.3 - January 25, 2021

FIXED: call to settings file now explicit from command-line (was not required until tns-marker added)

v0.4.2 - January 25, 2021

REFACTOR: requests will fail if TNS responds with any status other than 200
REFACTOR: added user-agent header now required by TNS (needs added in the settings file)

v0.4.1 - January 25, 2021

FEATURE:** you can now download and parse astronotes (including ability to add to MySQL database tables)
REFACTOR: Updated URL to the new TNS URL https://www.wis-tns.org

v0.3.2 - December 21, 2020

ENHANCEMENT: now using discovered_period_value for discInLastDays. More efficient than adding range of obsdate.

v0.3.1 - October 25, 2020

FIXED: bytes to string with utf-8 encoding bug stopping regexes from passing

v0.3.0 - May 22, 2020

Now compatible with Python 3.*

API Reference ∞

Modules ∞

`transientNamer.commonutils`	common tools used throughout package
`transientNamer.utKit`	Unit testing tools

Classes ∞

`transientNamer.astronotes`	Tools to download, parse and ingest astronote content into a MySQL database
`transientNamer.search`	Search the Transient Name Server with various search constraints

Functions ∞

transientNamer.commonutils.getpackagepath

getpackagepath

A-Z Index ∞

Modules

`transientNamer.commonutils`	common tools used throughout package
`transientNamer.utKit`	Unit testing tools

Classes

`transientNamer.astronotes`	Tools to download, parse and ingest astronote content into a MySQL database
`transientNamer.search`	Search the Transient Name Server with various search constraints

Functions