Welcome to the OTTER API documentation!#

Introduction#

Open mulTiwavelength Transient Event Repository (OTTER)#

OTTER is a catalog of data on transient sources. It is focused on tidal disruption event photometry for now but will expand in the future if the interest is there. This page hosts the documentation for OTTER API which allows users to easily access and visualize the complex multiwavelength datasets hosted in OTTER.

Please consider joining our slack workspace to join in on the conversation! This slack workspace will have announcements about downtimes and upgrades, and it’s a great place to ask questions! If the link has expired, please reach out to the developers.

Installation Quickstart#

MacOS & Linux User Installation#

For non-developers, the astro-otter API can be installed using pip:

python3 -m pip install astro-otter[standard]

Or, for a more minimal installation without the dependencies for the DataFinder or plotter modules:

python3 -m pip install astro-otter

Then, from a python terminal you can do things like

import otter
db = otter.Otter()
db.query(names="18hyz")

Note, we do not natively support Windows OS installation but do support WSL2 installation (see below). This is a change as of v0.7.0 and is because of the new dustmaps package requirement. The dustmaps code relies on healpy which does not support Windows.

Windows Installation#

Since we do not natively support Windows, we suggest installing and running Windows Subsystem for Linux (WSL2). You can follow the instructions on the Microsoft docs page to install WSL2. Once it is installed you can start a WSL2 terminal by running the wsl command in a powershell terminal. After running this command and entering the WSL2 terminal, you can return to MacOS & Linux User Installation.

Developer Installation#

For a local installation of everything, typically for developers, follow these steps instead:

First, install some other dependencies: a. ADS API: https://ads.readthedocs.io/en/latest/#getting-started b. Docker (install AND run):
Then, set the following environment variables in your .bashrc/.zshrc file:

export OTTER_ROOT=/path/to/where/to/clone
export ARANGO_URL=<insert url>
export ARANGO_ROOT_PASSWORD=<insert password>
export VETTING_PASSWORD=<insert password>
export ARANGO_USER_PASSWORD=<insert password>
export ADS_DEV_KEY=<insert api key>
export TNS_BOT_ID=<bot id>
export TNS_BOT_NAME=<bot name>
export TNS_API_KEY=<api key>
export OTTER_WEB_BASE_URL="/otter"

If you don’t know what any of the values should be, reach out to an existing developer

Source your .bashrc/.zshrc

source ~/.bashrc

Clone the relevant repositories

git clone https://github.com/astro-otter/otter.git $OTTER_ROOT/otter
git clone https://github.com/astro-otter/otterdb.git $OTTER_ROOT/otterdb
git clone https://github.com/astro-otter/otter-web.git $OTTER_ROOT/otter-web
git clone https://github.com/astro-otter/otter-docker.git $OTTER_ROOT/otter-docker

Install the otter python API from source and install our pre-commit hooks that help maintain code quality.

cd $OTTER_ROOT/otter
python -m pip install -e .
pre-commit install

Install the web application by running

cd $OTTER_DIR/otter-web
python3 -m pip install -e .

Run the web application in developer mode. Note that this will connect to the database at the environment variable ARANGO_URL. From the otter-web directory
```
python3 start.py
```
Test that the website is running by navigating to http://localhost:8080/otter
Assuming everything is working as expected, you are now able to change things as you wish!

Setting up a local copy of the database#

Hopefully, a developer should never need to setup a local copy of the database and can instead connect to the production database when modifying the web applications and API. In the unlikely scenario that a developer does need to setup a local copy of the database, they can follow these steps.

Get the database up and running:
1. First, make sure docker is running
2. If you have an arm64 cpu (like a Mac Silicon chip), you will need to build the docker container on that cpu architecture. From the otterdb directory run:
```
docker build -t otterdb:v0.3.6 .
```
3. Then run the docker container from dockerhub (if you built it locally, make sure you change the name at the bottom of this command)
```
docker run \
-e ARANGO_ROOT_PASSWORD=$ARANGO_ROOT_PASSWORD \
-e VETTING_PASSWORD=$VETTING_PASSWORD \
-e VETTING_USER="vetting-user" \
-e ARANGO_USER_USERNAME="user-guest" \
-e ARANGO_USER_PASSWORD=$ARANGO_USER_PASSWORD \
-e DB_LINK_PORT_8529_TCP="http://127.0.0.1:8529" \
-p 8529:8529 \
noahfranz13/otterdb:v0.3.6
```
4. Open a new terminal. Then, add a copy of the data to the database from the master copy at SciServer. From the otterdb directory, run
```
python3 import_from_sciserver.py
```
Test that arangodb is running correctly and the data is imported by navigating to http://localhost:8529 in a browser and logging in as user “root” and the password set by $ARANGO_ROOT_PASSWORD
Start the web application locally, connected to your local database, with
```
export ARANGO_URL="http://localhost:8529" && python3 start.py
```

Seeking Support, Reporting Issues, and Contributing#

Reporting Issues, Providing Feedback, and Seeking Support#

Please report any bugs, issues, or suggestions by opening an issue at astro-otter/otter#choose. You should also feel free to open an issue just with questions if something in the documentation is unclear. Typically, questions like these are very useful and will lead to additions or clarifications on our documentation page! We monitor new issues opened here and will provide additional guidance and/or next steps.

Contributing#

Please use the following Git/GitHub workflow if you wish to make contributions:

Fork this repository
Following the Developer Installation above to install the API locally. Feel free to open an issue or reach out with any problems.
When you have finished your contribution (or have reached a stable point in your development), please open a Pull Request from your fork.

We monitor the opened pull requests and will discuss any implementation details with you there, if necessary.