Usage#

hamcontestanalysis comprises a set of tools for radio amateurs dedicated to analyze contest with the maximum detail.

When installed, a full CLI is made available. This library has been structured into different modules as shown below, that provide the user with different capabilities:

hamcontestanalysis Usage: hamcontestanalysis [OPTIONS] COMMAND [ARGS]... Config logging through app settings. ╭─ Options ─────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰───────────────────────────────────────────────────────────────╯ ╭─ Commands ────────────────────────────────────────────────────╮ │dashboard                                              │ │download                                               │ │plot                                                   │ ╰───────────────────────────────────────────────────────────────╯

In the following, the different modules will be described.

Dashboard#

The dashboard can be run locally with the hamcontestanalysis dashboard command. There is currently one single dashboard (contest-analysis), but the package is prepared to easily add more if needed.

To run the contest analysis dashboard locally, type

hamcontestanalysis dashboard contest-analysis

The dashboard is shown in http://localhost:8050, although both the address and port can be easily changed with the appropiate call:

hamcontestanalysis dashboard Usage: hamcontestanalysis dashboard [OPTIONS] Dashboard main command line interface. ╭─ Options ─────────────────────────────────────────────────────╮ │--debugDebug the dashboard│ │--hostTEXT   Host to run the dashboard│ │[default: localhost]     │ │--portINTEGERPort to run the dashboard│ │[default: 8050]          │ │--helpShow this message and exit.│ ╰───────────────────────────────────────────────────────────────╯

Download#

Logs from any supported contest can be downloaded locally with the hamcontestanalysis download command. This command is automatically run when analysing a contest with a dashboard. However, this command is provided separately in case further independent analysis wants to be performed.

The downloading directory can be defined by setting the appropriate environment variable:

export HAMCONTESTANALYSISSTORAGE=/Users/my/folder/for/this/app

The following command downloads the desired log and stores it in parquet format.

hamcontestanalysis download main Usage: hamcontestanalysis download main [OPTIONS] Download main command line interface. ╭─ Options ─────────────────────────────────────────────────────╮ │*--contestTEXT   Name of the contest, e.g.     │ │cqww.                         │ │[default: None]               │ │[required]                    │ │*--yearsINTEGERYears to be considered. Can be│ │specified multiple times for  │ │multiple years.               │ │[default: None]               │ │[required]                    │ │*--modeTEXT   mode of the contest. Only     │ │available options: cw, ssb,   │ │rrty, mixed.                  │ │[default: None]               │ │[required]                    │ │*--callsignsTEXT   callsigns to be considered.   │ │Can be specified multiple     │ │times for multiple callsigns. │ │[default: None]               │ │[required]                    │ │--forceForce the download even if the│ │parquet file exists locally.  │ │Defaults to False.            │ │--helpShow this message and exit.│ ╰───────────────────────────────────────────────────────────────╯

Plots#

The different plots shown in the dashboard can also be produced and stored locally in html format, with the plot command.

The storage directory of the plots can be defined by setting the appropriate environment variable:

export HAMCONTESTANALYSISPLOTS=/Users/my/folder/for/the/plots
hamcontestanalysis plot Usage: hamcontestanalysis plot [OPTIONS] COMMAND [ARGS]... ╭─ Options ─────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰───────────────────────────────────────────────────────────────╯ ╭─ Commands ────────────────────────────────────────────────────╮ │band-conditions                Band conditions from RBN    │ │plot.                       │ │cqww-evolution                 CQ WW feature evolution     │ │plot.                       │ │cqww-minutes-from-previous-callMinutes since each callsign │ │called previously plot.     │ │cw-speed                       CW speed plot.              │ │frequency                      Frequency plot.             │ │log-heatmap                    Contest log heatmap plot    │ │plot.                       │ │number-rbn-spots               Number of RBN spots plot.   │ │qso-direction                  QSO direction plot.         │ │qsos-hour                      Qso's per hour plot.        │ │rate                           QSO rate plot.              │ │rolling-rate                   QSO rolling rate plot.      │ │snr                            Average SNR plot.           │ │snr-band-continent             Average SNR plot per band   │ │and continent.              │ ╰───────────────────────────────────────────────────────────────╯

Each of the plots can have different arguments, that can be visualized with the option --help.

Library#

The hamcontestanalysis package can also be used as a library. Below are examples with some useful code snippets:

Load data#

Contest data There are currently four contests supported: CQ WW (cqww), CQ WPX (cqwpx), IARU HF (iaru), and ARRL DX (arrldx). The following command shows how to load the data for a particular contest, year, mode and callsign into a pandas data frame.

from hamcontestanalysis.data.cqww.storage_source import CabrilloDataSource

data = CabrilloDataSource(callsign="EF6T", year="2023", mode="cw").load()

A list with all the available call signs per contest, year, and category can be obtained with the following command:

from hamcontestanalysis.data.cqww.storage_source import CabrilloDataSource

list_of_callsigns = CabrilloDataSource._get_available_callsigns(year=2023, mode="cw")

RBN data#

Reverse Beacon data (RBN) can be loaded with the following command, either for a certain contest (only those supported), or for a custom date.

from datetime import date
from hamcontestanalysis.data.rbn.storage_source import ReverseBeaconRawDataSource

data_from_custom_date = ReverseBeaconRawDataSource(year=2024, mode="cw", dates=[date(2024, 4, 23)]).load()
data_from_contest = ReverseBeaconRawDataSource(year=2023, mode="cw", contest="cqww").load()