Features

Get notified whenever there are good chances of seeing northern lights! Follow @NorthernLightsForecastBot on telegram for updates on the Tromsø magnetometer, or set up your own telegram bot with this project. Setting up a telegram bot is easy as pie, just follow this guide.

Requirements

The project uses tesseract to read the scale off a magnetogram plot. See installation instructions below.

Installation

Clone the repository:

git clone https://github.com/engeir/northern-lights-forecast.git nlf && cd nlf

Install tesseract, used with the package pytesseract.

Then get yourself a telegram bot using this guide.

Set up a virtual environment and activate. (Use whatever, for example poetry: poetry shell.)

Now we are ready to install the project; run poetry install in the root of the project.

Set up a cron job:

sh crontab.sh

Running sh croptab.sh -p will print to the console instead of installing a new cron job. It is important to get the correct path to the python virtual environment, therefore, the shell script must be run when the virtual environment is activated. To be certain everything is set up correctly you may want to run poetry run sh croptab.sh.

The cron script will try to start the bot daemon every 10 minutes. The PID for the process is saved to $HOME/.local/share/nlf/nlf-bot.pid. To stop the bot daemon, run

nlfd --stop

The daemon can also be started manually with

nlfd

Usage

Please see the Command-line Reference for details. Below is the output of nlf --help:

Usage: nlf [OPTIONS]

  Northern Lights Forecast.

Options:
  --version                     Show the version and exit.
  -l, --location TEXT           Which magnetometer to use. Run with '--
                                locations' option to list all available
                                locations.  [default: Tromsø]

  --locations / --no-locations  List out available magnetometer locations.
                                [default: False]

  --test / --no-test            Test sending message to telegram.  [default:
                                False]

  --help                        Show this message and exit.

Telegram

It is also possible to visit the telegram bot (@NorthernLightsForecastBot) and query for forecasts live. This includes the commands:

• /start and /help: this will do the same thing, greet you with a helpful message

• /version: which will print out the version of the project

• /locations: which will print out the valid locations a forecast can be obtained from

• Forecast <location>: that is, any message that starts with the word forecast and has a valid location as any of the succeeding words.

How?

The script implements an automated Northern Lights forecast by taking advantage of the web site of Tromsø Geophysical Observatory (TGO).

Image analysis

The script will try to download a .gif file with plots of the components of a magnetometer. One component is all that is needed (blue line) and the script will then locate the blue pixels and fit a graph to the pixel locations with a Savitzky-Golay filter.

Below is an example with the original image above the new reverse engineered graph.

At a given threshold of the derivative of the X component of a magnetometer in Tromsø (or one of the supported locations, see nlf --locations), a notification is sent to a telegram bot to let the user know of the current substorm event.

Cron

The script can be run every hour from 18:00 through 08:00 during the months September through March, using cron to automate the task. Run

sh crontab.sh

to set this up, or edit the cron script manually with

env EDITOR=nano crontab -e

The general form of how you edit cron is as shown below, but to get the exact string you can run sh crontab.sh -p, where the option -p will make the script print to the console rather than edit cron. The same options can be used when running the script as a cron job as is specified in the Command-line Reference (e.g.the -l option).

0 0-8,18-23 * 9-12,1-3 * export DISPLAY=:0 && cd /path/to/folder/containing/script && python src/northern_lights_forecast/__main__.py > t.txt 2>&1

To change when the script is run, edit the cron scheduling to a custom setting: https://crontab.guru/

The crontab.sh script will try to find the tesseract executable and add this to path, which is needed for the cronjob to work. If it cannot find tesseract, a comment is instead printed warning about this, and you have to verify the installation of tesseract and possibly add it to path manually.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Northern Lights Forecast is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @cjolowicz’s Hypermodern Python Cookiecutter template.