deploy: 4303ec9

HiSPARC · Aug 27, 2024 · cbe9464 · cbe9464
commit cbe9464
Show file tree

Hide file tree

Showing 51 changed files with 4,152 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 759cacd2efa7edef049a9f9d1e1f8d68
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.doctrees/data_retrieval.doctree b/.doctrees/data_retrieval.doctree
diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle
diff --git a/.doctrees/event-display.doctree b/.doctrees/event-display.doctree
diff --git a/.doctrees/index.doctree b/.doctrees/index.doctree
diff --git a/.doctrees/jsparc_analysis.doctree b/.doctrees/jsparc_analysis.doctree
diff --git a/.doctrees/station_distances.doctree b/.doctrees/station_distances.doctree
diff --git a/.nojekyll b/.nojekyll
diff --git a/_images/data_overview.png b/_images/data_overview.png
diff --git a/_images/data_preview.png b/_images/data_preview.png
diff --git a/_images/event-display.png b/_images/event-display.png
diff --git a/_images/event-display_cluster.png b/_images/event-display_cluster.png
diff --git a/_images/event-display_legend.png b/_images/event-display_legend.png
diff --git a/_images/event_traces.png b/_images/event_traces.png
diff --git a/_images/get_data.png b/_images/get_data.png
diff --git a/_images/jsparc_coincidence_traces.png b/_images/jsparc_coincidence_traces.png
diff --git a/_images/jsparc_flux.png b/_images/jsparc_flux.png
diff --git a/_images/jsparc_get_data.png b/_images/jsparc_get_data.png
diff --git a/_images/jsparc_map.png b/_images/jsparc_map.png
diff --git a/_images/jsparc_station_traces.png b/_images/jsparc_station_traces.png
diff --git a/_images/jsparc_zoom_traces.png b/_images/jsparc_zoom_traces.png
diff --git a/_images/plot.png b/_images/plot.png
diff --git a/_images/plot_options.png b/_images/plot_options.png
diff --git a/_sources/data_retrieval.rst.txt b/_sources/data_retrieval.rst.txt
@@ -0,0 +1,196 @@
+.. include:: subst.inc
+
+Data retrieval
+==============
+
+This page describes the functions of the `Data retrieval
+<https://data.hisparc.nl/media/jsparc/data_retrieval.html>`_ web
+application. With this web application you can retrieve |hisparc| data,
+with which you can make plots.
+
+Here is a step by step guide for the functions of the page.
+
+
+Get data
+--------
+
+The page will be quite empty at first and only show the |hisparc| logo
+and two forms with which you can either download data or load local
+datafiles. Whenever the |hisparc| logo becomes animated, it indicates
+that data is being retrieved from the |hisparc| servers.
+
+.. _get_data:
+.. figure:: images/get_data.png
+   :align: center
+   :width: 425
+
+   The two forms to load data and the |hisparc| logo indicating activity.
+
+
+Download data
+^^^^^^^^^^^^^
+
+If you choose to download data you can first select a |hisparc| station,
+the start and end date (and time) and the type of data you want to get.
+Once you have made your choices click *Get Data!*.
+
+
+Local data
+^^^^^^^^^^
+
+If you already have a .tsv file (tab-separated values) on your computer,
+you can load that into the web application. The application will try to
+interpert the filename of the .tsv the following way: *[data
+type]-s[station number]-[start date]_[end date]*. If the data type is
+one of the types provided by the |hisparc| Public Database the web
+application tries to identify the columns, otherwise it will simply
+give each column a number.
+
+
+Data overview
+-------------
+
+Once the data has been (down)loaded a new section on the website
+appears, giving you and overview of all the datasets that you have. It
+is possible to get multiple datasets, simply use the form again to get
+another.
+
+For each downloaded dataset you can see the options that were used in
+the form, the number of entries it contains. Each row also has controls
+to choose, preview, download and remove a dataset.
+
+.. _data_overview:
+.. figure:: images/data_overview.png
+   :align: center
+   :width: 425
+
+   An overview of the loaded datasets.
+
+
+Controls
+^^^^^^^^
+
+Here you can choose which datasets you wish to use for creating plots by
+selecting them in the *Choice* columns. The *Preview* button creates a
+table overview of the dataset. The *Download* button downloads the dataset
+as a .tsv file (tab-separated), which can be imported in other
+applications like Excel. Finally there is a *Remove* button, this simply
+removes the dataset from the browser memory.
+
+
+Plot options
+------------
+
+Once you have chosen at least one dataset (with the *Choice* column) the
+plot controls appear, with which you can select the type of plots you
+want to create: *Scatter*, *Histogram* or a *Time series*. You can also
+choose whether to display the x and y axes as linear or logarithmic and
+the number of bins for the histogram plot.
+
+To the right of these options are the available variables from the
+chosen dataset, you can choose which variable to use for the x, and
+which to use for the y-axis. After selecting a plot type which requires
+only one variable, the other axis column will be disabled. For instance
+a histogram requires only x-axis values, the y-axis values are the
+number of counts in each bin, so the y-axis selection will be disabled.
+
+Once you have made your choices you can click the *Create Plot* button
+and the plot will be shown in a new section appearing under these
+options. If you wish to create a different plot, simply change the
+options and click *Create Plot* button again.
+
+.. _plot_options:
+.. figure:: images/plot_options.png
+   :align: center
+   :width: 425
+
+   Options for creating plots and variable lists to select which
+   variables to plot.
+
+
+Interpolation
+^^^^^^^^^^^^^
+
+It is possible to get multiple datasets and then select one dataset as
+choice 1 and another as choice 2. When two datasets are chosen the
+variables for each dataset will appear side by side, and variables for
+the x or y axes can be chosen from either dataset. If the x and y data
+are from different datasets the data will be interpolated to match the
+different timestamps. This can cause strange values in some cases,
+especially when the start and end dates for the two datasets do not
+match.
+
+
+Plot
+----
+
+The plot view appears as soon as you click *Create Plot*. On the top
+right is a *Save image* button that will open a new window with a .png
+version of the plot, which can be saved to your pc. Currently there are
+no options to change axis limits (zoom in, move around).
+
+.. _plot:
+.. figure:: images/plot.png
+   :align: center
+   :width: 425
+
+   An example plot of barometer data.
+
+
+Data preview
+------------
+
+If you click the *show* button for a dataset this section will show a
+table with some rows of data. Each row shows all variables in the
+dataset for each event. At first a small subset will be shown, since it
+would take the browser to long to display all data rows. You can shows
+more by clicking the line in the middle of the shown data. However, if
+you wish to see all data, it is better to download the data to your pc.
+
+.. _data_preview:
+.. figure:: images/data_preview.png
+   :align: center
+   :width: 425
+
+   The data preview table showing the raw values in the dataset.
+
+
+Event traces
+^^^^^^^^^^^^
+
+Cosmic-ray events consist of signal measurements from each PMT with a
+scintillator detector. Variables like *Pulseheight* and *Arrival time*
+are derived from these signals. These signals are referred to as
+*traces*. When looking at the data for a cosmic-ray dataset the last
+column is called *Traces* and will contains *show* buttons for each
+event. When clicked, the traces are retrieved and them shown in the plot.
+
+.. _event_traces:
+.. figure:: images/event_traces.png
+   :align: center
+   :width: 425
+
+   The traces of a chosen event.
+
+
+Multiple detectors
+------------------
+
+Depending on your choice of variables a plot may contain datapoints with
+multiple colors, this is because some variables are measured by multiple
+detectors. For cosmic-ray data there are either 2 or 4 detectors for the
+*Pulseheights*, *Integral*, *Number of mips* and *Arrival times*, the
+colors are respectively black, red, green and blue. For weather data the
+*Temperature* and *Humidity* are measured both indoor (black) and
+outdoor (red).
+
+
+Missing data
+------------
+
+When a weather sensor is out of duty or a cosmic-ray station has 2
+detectors instead of 4, the missing data will be given the value -999 or
+-1. Those error values are omitted in the plot, preventing distortions
+of the plot limits. A problem can arise when working with temperatures
+that include -1 °C, because the filter will remove it, though it is a
+valid measurement. Luckily a temperature of -1 °C is fairly rare.
diff --git a/_sources/event-display.rst.txt b/_sources/event-display.rst.txt
@@ -0,0 +1,87 @@
+.. include:: subst.inc
+
+Event display
+=============
+
+This page describes how the `Event display
+<https://data.hisparc.nl/media/jsparc/event-display/>`_ works. With this
+web application you can see |hisparc| events occuring on a map.
+
+.. _event-display:
+.. figure:: images/event-display.png
+   :align: center
+   :width: 500
+
+   The event display for Science Park.
+
+
+Markers
+-------
+
+The map will show two kinds of markers:
+
+- **events** are air showers detected by a single |hisparc| station
+- **coincidences** are air showers detected by multiple |hisparc| stations
+  simultaneously
+
+Their respective colors are shown in the legend in the topright.
+
+.. _event-display_legend:
+.. figure:: images/event-display_legend.png
+   :align: center
+   :width: 134
+
+   Marker legend.
+
+
+Choose cluster
+--------------
+
+In the bottom right of the page is a dropdown menu from which a
+subcluster can be selected. Events and coincidences from the chosen
+subcluster will be shown on the map.
+
+The chosen subcluster will be set as the location hash of the page. So
+if Amsterdam is chosen the url ends in ``#amsterdam``. If the page is
+loaded without a hash it will default to the Science Park cluster,
+automatically setting the hash to that value.
+
+.. _event-display_cluster:
+.. figure:: images/event-display_cluster.png
+   :align: center
+   :width: 178
+
+   Menu to choose the cluster.
+
+
+JSON data
+---------
+
+The page works by loading pregenerated JSON data.
+
+- First a station JSON is loaded. This contains a list of stations and
+  their locations, and the start and end timestamps of the dataset. The
+  start and end timestamps are used to align the individual events and
+  coincidences.
+
+- Then a JSON with a list of events is loaded for each of these stations.
+  For each event the exact timestamp and number of particles is given.
+  The timestamps are used to playback the events in real-time, since the
+  time between consecutive events is known. The number of particles is
+  used to determine the size of the marker.
+
+- Finally a JSON with coincidences between the stations is loaded. This
+  contains similar data like the event JSONs, but then for each shower the
+  number of particles for each participating station.
+
+In the `source code
+<https://github.com/HiSPARC/jsparc/tree/master/event-display>`_ the
+Python script that creates the JSONs can be found. The JSON data is
+loaded with relative paths, so if ran locally you can supply your own
+data.
+
+.. note::
+
+    If you want to use Chrome when running this page locally it needs to be
+    started with the ``--allow-file-access-from-files`` option.
+
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,30 @@
+.. include:: subst.inc
+
+Welcome to jSparc's documentation!
+==================================
+
+This documentation describes |jsparc|, a JavaScript library for web
+applications. Also included are the manuals for the various web
+applications that have been made with the library.
+
+The |jsparc| library makes it easy to access the |hisparc| Public
+Database API, download cosmic-ray and weather data, interpolate between
+different datasets, create histograms, and much more!
+
+Several web applications are based on this library, here are some guides
+to using those.
+
+The source code can be found on `GitHub
+<https://github.com/HiSPARC/jsparc/>`_.
+
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   data_retrieval
+   event-display
+   jsparc_analysis
+   station_distances