From 3192ce42b4de1d5ee04b632b26c654c156bea584 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 14:57:31 +0200 Subject: [PATCH 01/34] simplified main L1 diagram started to split out sub-diagrams --- source/specification/level-1/common.inc | 12 ++++++ source/specification/level-1/level-1.plantuml | 40 ++++++++----------- .../specification/level-1/pointing.plantuml | 10 +++++ 3 files changed, 39 insertions(+), 23 deletions(-) create mode 100644 source/specification/level-1/common.inc create mode 100644 source/specification/level-1/pointing.plantuml diff --git a/source/specification/level-1/common.inc b/source/specification/level-1/common.inc new file mode 100644 index 0000000..a8fd5dc --- /dev/null +++ b/source/specification/level-1/common.inc @@ -0,0 +1,12 @@ +hide circles +hide methods +skinparam ClassBackgroundColor white/aliceblue +skinparam ClassHeaderBackgroundColor lightblue +skinparam backgroundcolor transparent + + diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index 33b65e5..9016dbd 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -1,18 +1,7 @@ @startuml -hide circles -hide methods -skinparam ClassBackgroundColor white/aliceblue -skinparam ClassHeaderBackgroundColor lightblue -skinparam backgroundcolor transparent - - +!include common.inc -package IVOA { +package IVOA <> { class ObsCore { } @@ -30,31 +19,36 @@ package VODF.L1 { class Observation #line.bold { + obs_id + -- + time_interval + spatial_region : SkyRegion - + instrument_name + ... } - Observation "1" -- "0..1" Pointing + class ObservationCollection { + + } + + ObsCore -r- Observation : "maps to <" - Pointing <|-- NominalPointing - Pointing <|-- TimeSeriesPointing DataRelease "1..*" -- "1" ObservationCollection ObservationCollection "1" -- "1..*" Observation - ObsCore -r- Observation : "maps to <" + + Observation "1" -l- "1" Instrument + Observation "1" -r- "0..1" Pointing + Observation "1" -- "1..*" OnTime Observation "1" -- "0..1" EventList Observation "0..*" *-- "0..1" IRF - Observation "1" -- "1..*" OnTime - OnTime <|-- SingleOnTime - OnTime <|-- TimeSeriesOnTime - EventList "1" -- "0..*" Event - Event "properties" -- "dimensions" IRFComponent + ' removed for now: add to separate sub-diagram + 'OnTime <|-- SingleOnTime + 'OnTime <|-- TimeSeriesOnTime + 'EventList "1" -- "0..*" Event + IRF "1" *-- "1..*" IRFComponent diff --git a/source/specification/level-1/pointing.plantuml b/source/specification/level-1/pointing.plantuml new file mode 100644 index 0000000..13892ac --- /dev/null +++ b/source/specification/level-1/pointing.plantuml @@ -0,0 +1,10 @@ +@startuml +!include common.inc + +class NominalPointing <> +class TimeSeriesPointing <> + +Pointing <|-- NominalPointing +Pointing <|-- TimeSeriesPointing + +@enduml From b869c119bb05900d7bd82f98aa0570553b7d5871 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 14:58:30 +0200 Subject: [PATCH 02/34] added pointing diagram --- source/specification/level-1/pointing.plantuml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/specification/level-1/pointing.plantuml b/source/specification/level-1/pointing.plantuml index 13892ac..bfcfd4e 100644 --- a/source/specification/level-1/pointing.plantuml +++ b/source/specification/level-1/pointing.plantuml @@ -1,10 +1,12 @@ @startuml !include common.inc -class NominalPointing <> -class TimeSeriesPointing <
> -Pointing <|-- NominalPointing -Pointing <|-- TimeSeriesPointing +package VODF.L1 { + class NominalPointing <> + class TimeSeriesPointing <
> + Pointing <|-- NominalPointing + Pointing <|-- TimeSeriesPointing +} @enduml From b66c75d9ed797f4395c1f33ec34cb4dc8798637b Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 15:00:16 +0200 Subject: [PATCH 03/34] added ontime diagram --- source/specification/level-1/ontime.plantuml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 source/specification/level-1/ontime.plantuml diff --git a/source/specification/level-1/ontime.plantuml b/source/specification/level-1/ontime.plantuml new file mode 100644 index 0000000..20eda4e --- /dev/null +++ b/source/specification/level-1/ontime.plantuml @@ -0,0 +1,13 @@ +@startuml +!include common.inc + + +package VODF.L1 { + + class SingleOnTime <> + class TimeSeriesOnTime <
> + + OnTime <|-- SingleOnTime + OnTime <|-- TimeSeriesOnTime +} +@enduml From c2138c7deaa681170579bb148f0c69c2497da7af Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 15:06:44 +0200 Subject: [PATCH 04/34] added event-list diagram --- .../specification/level-1/eventlist.plantuml | 26 +++++++++++++++++++ .../specification/level-1/pointing.plantuml | 6 +++-- 2 files changed, 30 insertions(+), 2 deletions(-) create mode 100644 source/specification/level-1/eventlist.plantuml diff --git a/source/specification/level-1/eventlist.plantuml b/source/specification/level-1/eventlist.plantuml new file mode 100644 index 0000000..9b4fc39 --- /dev/null +++ b/source/specification/level-1/eventlist.plantuml @@ -0,0 +1,26 @@ +@startuml +!include common.inc + + +package VODF.L1 { + + class EventList + class Event { + + ra_reco + + dec_reco + + time_reco + + energy_reco + } + + class SimulatedEvent { + + ra_true + + dec_true + + time_true + + energy_true + + particle_type_true + } + + EventList "1" o-- "0..*" Event + Event -r-|> SimulatedEvent +} +@enduml diff --git a/source/specification/level-1/pointing.plantuml b/source/specification/level-1/pointing.plantuml index bfcfd4e..d3b431d 100644 --- a/source/specification/level-1/pointing.plantuml +++ b/source/specification/level-1/pointing.plantuml @@ -3,10 +3,12 @@ package VODF.L1 { - class NominalPointing <> - class TimeSeriesPointing <
> + class NominalPointing + class TimeSeriesPointing Pointing <|-- NominalPointing Pointing <|-- TimeSeriesPointing + + TimeSeriesPointing "1" o-- "1..*" PointingMeasurement } @enduml From c1665860ffe9e3f116b7ef86fde0c48db822b9c1 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 15:12:18 +0200 Subject: [PATCH 05/34] cleaned up how time-series relate to measurements --- source/specification/level-1/level-1.plantuml | 7 ------- source/specification/level-1/ontime.plantuml | 8 ++++++-- source/specification/level-1/pointing.plantuml | 12 +++++++++--- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index 9016dbd..afc2770 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -43,13 +43,6 @@ package VODF.L1 { Observation "1" -- "0..1" EventList Observation "0..*" *-- "0..1" IRF - - ' removed for now: add to separate sub-diagram - 'OnTime <|-- SingleOnTime - 'OnTime <|-- TimeSeriesOnTime - 'EventList "1" -- "0..*" Event - - IRF "1" *-- "1..*" IRFComponent } diff --git a/source/specification/level-1/ontime.plantuml b/source/specification/level-1/ontime.plantuml index 20eda4e..b7c6c68 100644 --- a/source/specification/level-1/ontime.plantuml +++ b/source/specification/level-1/ontime.plantuml @@ -4,10 +4,14 @@ package VODF.L1 { - class SingleOnTime <> - class TimeSeriesOnTime <
> + abstract class OnTime + + class SingleOnTime + class TimeSeriesOnTime OnTime <|-- SingleOnTime OnTime <|-- TimeSeriesOnTime + + TimeSeriesOnTime o-- "1..*" SingleOnTime } @enduml diff --git a/source/specification/level-1/pointing.plantuml b/source/specification/level-1/pointing.plantuml index d3b431d..ec3fd9b 100644 --- a/source/specification/level-1/pointing.plantuml +++ b/source/specification/level-1/pointing.plantuml @@ -3,12 +3,18 @@ package VODF.L1 { - class NominalPointing + abstract class Pointing + + class SinglePointing class TimeSeriesPointing - Pointing <|-- NominalPointing + Pointing <|-- SinglePointing + Pointing <|-- TimeSeriesPointing + TimeSeriesPointing "1" o-- "1..*" SinglePointing + + SinglePointing <|-- HorizontalSinglePointing + SinglePointing <|-- CelestialSinglePointing - TimeSeriesPointing "1" o-- "1..*" PointingMeasurement } @enduml From cb25e812c4f4e3618e622f8b345ea17b9cb3bc77 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 15:42:50 +0200 Subject: [PATCH 06/34] add IRF --- source/specification/level-1/index.rst | 33 +++++++++++++++++++++++ source/specification/level-1/irf.plantuml | 23 ++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 source/specification/level-1/irf.plantuml diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index 6966845..d6dcd46 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -56,5 +56,38 @@ Data Releases TBD +EventList +---------- + +.. uml:: eventlist.plantuml + :caption: VODF **Level-1 EventList** Data Model + :width: 30em + +IRF +--- + +.. uml:: irf.plantuml + :caption: VODF **Level-1 IRF** Data Model + :width: 40em + + +OnTime +------ + +.. uml:: ontime.plantuml + :caption: VODF **Level-1 OnTime** Data Model + :width: 25em + + +Pointing +-------- + +.. uml:: pointing.plantuml + :caption: VODF **Level-1 Pointing** Data Model + :width: 34em + + + + Data Products ============= diff --git a/source/specification/level-1/irf.plantuml b/source/specification/level-1/irf.plantuml new file mode 100644 index 0000000..b04423c --- /dev/null +++ b/source/specification/level-1/irf.plantuml @@ -0,0 +1,23 @@ +@startuml +!include common.inc + +package VODF.L1 { + + abstract class IRF + abstract class IRFComponent + class EffectiveArea <> + class BackgroundRate <> + class EnergyMigration <> + class PSF <> + + IRF *-- "1..*" IRFComponent + + + IRF <|-- StandardIRF + + StandardIRF *-- EffectiveArea + StandardIRF *-- BackgroundRate + StandardIRF *-- EnergyMigration + StandardIRF *-- PSF + +} From 702fb2122d3cadec267890e352633c460d746d6b Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 15:59:14 +0200 Subject: [PATCH 07/34] move common plantuml style file up --- source/specification/{level-1 => }/common.inc | 2 ++ source/specification/level-1/eventlist.plantuml | 2 +- source/specification/level-1/irf.plantuml | 2 +- source/specification/level-1/level-1.plantuml | 2 +- source/specification/level-1/ontime.plantuml | 2 +- source/specification/level-1/pointing.plantuml | 2 +- source/specification/level-2/level-2.plantuml | 12 +----------- 7 files changed, 8 insertions(+), 16 deletions(-) rename source/specification/{level-1 => }/common.inc (92%) diff --git a/source/specification/level-1/common.inc b/source/specification/common.inc similarity index 92% rename from source/specification/level-1/common.inc rename to source/specification/common.inc index a8fd5dc..02c5007 100644 --- a/source/specification/level-1/common.inc +++ b/source/specification/common.inc @@ -1,3 +1,4 @@ +@startuml hide circles hide methods skinparam ClassBackgroundColor white/aliceblue @@ -10,3 +11,4 @@ package { FontColor gray } +@enduml diff --git a/source/specification/level-1/eventlist.plantuml b/source/specification/level-1/eventlist.plantuml index 9b4fc39..8269bee 100644 --- a/source/specification/level-1/eventlist.plantuml +++ b/source/specification/level-1/eventlist.plantuml @@ -1,5 +1,5 @@ @startuml -!include common.inc +!include ../common.inc package VODF.L1 { diff --git a/source/specification/level-1/irf.plantuml b/source/specification/level-1/irf.plantuml index b04423c..adc6bc1 100644 --- a/source/specification/level-1/irf.plantuml +++ b/source/specification/level-1/irf.plantuml @@ -1,5 +1,5 @@ @startuml -!include common.inc +!include ../common.inc package VODF.L1 { diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index afc2770..f0b866d 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -1,5 +1,5 @@ @startuml -!include common.inc +!include ../common.inc package IVOA <> { class ObsCore { diff --git a/source/specification/level-1/ontime.plantuml b/source/specification/level-1/ontime.plantuml index b7c6c68..f425979 100644 --- a/source/specification/level-1/ontime.plantuml +++ b/source/specification/level-1/ontime.plantuml @@ -1,5 +1,5 @@ @startuml -!include common.inc +!include ../common.inc package VODF.L1 { diff --git a/source/specification/level-1/pointing.plantuml b/source/specification/level-1/pointing.plantuml index ec3fd9b..2db61f8 100644 --- a/source/specification/level-1/pointing.plantuml +++ b/source/specification/level-1/pointing.plantuml @@ -1,5 +1,5 @@ @startuml -!include common.inc +!include ../common.inc package VODF.L1 { diff --git a/source/specification/level-2/level-2.plantuml b/source/specification/level-2/level-2.plantuml index 3382c5c..9ab757d 100644 --- a/source/specification/level-2/level-2.plantuml +++ b/source/specification/level-2/level-2.plantuml @@ -1,15 +1,5 @@ @startuml -hide circles -hide methods -skinparam ClassBackgroundColor white/aliceblue -skinparam ClassHeaderBackgroundColor lightblue - - +!include ../common.inc VODF.L1.Observation "1..*" -- "1" VODF.L2.DataSetCollection From 133d8223cbc358235c951fab23f001c772089a2c Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 16:07:35 +0200 Subject: [PATCH 08/34] mention DataLink in ObsCore --- source/specification/level-1/level-1.plantuml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index f0b866d..a2d0cfa 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -2,9 +2,9 @@ !include ../common.inc package IVOA <> { - class ObsCore { - - } + class ObsCore + class DataLink + ObsCore -l- DataLink } package VODF.L1 { @@ -29,7 +29,7 @@ package VODF.L1 { } - ObsCore -r- Observation : "maps to <" + IVOA -- Observation : "maps to <" DataRelease "1..*" -- "1" ObservationCollection From ff04cf60ef740148ee9f0d4b3b4aeca4e4fe0676 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 23 Apr 2025 16:39:14 +0200 Subject: [PATCH 09/34] improve IVOA linking --- source/specification/level-1/level-1.plantuml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index a2d0cfa..2e22ff8 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -1,10 +1,11 @@ @startuml !include ../common.inc +skinparam linetype ortho package IVOA <> { class ObsCore class DataLink - ObsCore -l- DataLink + ObsCore -- DataLink } package VODF.L1 { @@ -29,7 +30,8 @@ package VODF.L1 { } - IVOA -- Observation : "maps to <" + ObsCore .. Observation : "<> >" + DataLink .. Observation : "<> >" DataRelease "1..*" -- "1" ObservationCollection @@ -37,7 +39,7 @@ package VODF.L1 { Observation "1" -l- "1" Instrument - Observation "1" -r- "0..1" Pointing + Observation "1" -- "1" Pointing Observation "1" -- "1..*" OnTime Observation "1" -- "0..1" EventList From 18afa868aa0cadb505622fc147d00a14650245e5 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Thu, 24 Apr 2025 10:36:21 +0200 Subject: [PATCH 10/34] fix the diagram scaling no longer specify width, but fix it in the CSS so all diagrams use the same scale. --- source/_static/custom.css | 7 +++++++ source/specification/common.inc | 2 ++ source/specification/level-1/index.rst | 6 ------ source/specification/level-2/index.rst | 1 - 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/source/_static/custom.css b/source/_static/custom.css index f855117..5cd11c2 100644 --- a/source/_static/custom.css +++ b/source/_static/custom.css @@ -11,3 +11,10 @@ html[data-theme="light"] { html[data-theme="dark"] { --pst-color-primary: #8800ff; } + + +/* Ensure the SVG diagrams scale with font size, not diagram width */ +img[src$=".svg"] { + max-width: 100%; + height: auto; +} diff --git a/source/specification/common.inc b/source/specification/common.inc index 02c5007..7459a7b 100644 --- a/source/specification/common.inc +++ b/source/specification/common.inc @@ -4,6 +4,8 @@ hide methods skinparam ClassBackgroundColor white/aliceblue skinparam ClassHeaderBackgroundColor lightblue skinparam backgroundcolor transparent +skinparam DefaultFontSize 14 +skinparam DefaultFontName "Arial" + + + @enduml diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index 8084fea..5d2d0bb 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -3,14 +3,14 @@ skinparam linetype ortho package IVOA <> { - class ObsCore - class DataLink + class ObsCore #gray + class DataLink #gray ObsCore -- DataLink } package VODF { - class Facility #lightgray - class Instrument #lightgray + class Facility #gray + class Instrument #gray Facility -- Instrument : <> > } From f12977ba8116eed107b47ff8f88d5e722bb7cd2f Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Tue, 29 Apr 2025 12:03:35 +0200 Subject: [PATCH 18/34] define <> style for classes out of VODF --- source/specification/common.inc | 22 +++++++++++++++---- source/specification/level-1/level-1.plantuml | 9 ++++---- 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/source/specification/common.inc b/source/specification/common.inc index 818defe..4a0b951 100644 --- a/source/specification/common.inc +++ b/source/specification/common.inc @@ -1,8 +1,6 @@ @startuml hide circles hide methods -skinparam ClassBackgroundColor white-aliceblue -skinparam backgroundcolor transparent skinparam DefaultFontSize 14 skinparam DefaultFontName "Arial" @@ -14,16 +12,32 @@ package { FontColor gray } + + class { - Header { + + BackgroundColor white-aliceblue + header { FontColor #white BackgroundColor #8800ff - FontStyle bold + FontStyle bold } + +} + + +.extern { + class { + header { + BackgroundColor #gray + } + } + } +hide <> stereotype @enduml diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index 5d2d0bb..0919d56 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -3,16 +3,15 @@ skinparam linetype ortho package IVOA <> { - class ObsCore #gray - class DataLink #gray + class ObsCore <> {} + class DataLink <> {} ObsCore -- DataLink } package VODF { - class Facility #gray - class Instrument #gray + class Facility + class Instrument Facility -- Instrument : <> > - } From 3663734041a1f0eb9430857143ae4810eae99f69 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Tue, 29 Apr 2025 14:18:22 +0200 Subject: [PATCH 19/34] ensure stereotype color is correct --- source/specification/common.inc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/specification/common.inc b/source/specification/common.inc index 4a0b951..56f896a 100644 --- a/source/specification/common.inc +++ b/source/specification/common.inc @@ -8,19 +8,17 @@ skinparam DefaultFontName "Arial" +skinparam classStereotypeFontColor white + hide <> stereotype From 376b75c934b1442eed246376f66bdd6ea43daca8 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Tue, 29 Apr 2025 15:07:54 +0200 Subject: [PATCH 20/34] start to describe IRFs --- source/specification/level-1/index.rst | 45 ++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index 52736e0..42197ef 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -66,6 +66,51 @@ IRF .. uml:: irf.plantuml :caption: VODF **Level-1 IRF** Data Model +The :term:`IRF` contains the information necessary to map instrumental +:term:`reconstructed` parameters of the event to *physical* parameters, i.e. it +allows one to transform from a physical *flux* in a given space-time-spectral +interval into a predicted number of detected *counts* for a given instrument. + +.. tip:: + + Science analysis with event-counting instruments often involves fitting a + physical model to observed data. The standard technique is a *maximum + likelihood fit* using *forward folding*, where the physical model is passed + through the IRF to transform flux (physical units) into predicted counts + (instrumental units), and the fit is performed on this transformed quantity + by comparing the predicted to measured counts. The opposite process, + *unfolding*, where instrumental uncertainties are removed by deconvolution + and the model is fit in physical units gives very unstable results when data + are noisy and contain background events. + + + +StandardIRF +~~~~~~~~~~~ + +In current instruments, the :term:`IRF` is typically decomposed into the +following components, which each provide a value as a function of a given point +in true (physical) coordinates, i.e. the spatial position in the FOV, time, +energy, or instrumental coordinates like zenith angle, azimuth, event +reconstruction type, etc. + +Effective Collection Area (``EffectiveArea``) + Blah. + +Point-Spread Function (``PSF``) + Blah. + +Energy Migration Matrix (``EnergyMigration``) + Blah. + +Background Rate (``BackgroundRate``) + The expected rate of background events (in counts/second). Often, the real + rate is difficult to compute correctly without real data due to e.g. + atmospheric uncertainties, and therefore it is important to note that it may + need to be calibrated using real data. I.e. the shape should be correct, but + the normalization may need to be refined. + + OnTime ------ From 16984fde9b1b7c620d5650a77d85a012258eda44 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Tue, 29 Apr 2025 18:27:52 +0200 Subject: [PATCH 21/34] added Coverage and some text for IRFs --- source/conf.py | 1 + .../specification/level-1/coverage.plantuml | 38 +++++++++++++++ source/specification/level-1/index.rst | 47 ++++++++++++------- source/specification/level-1/irf.plantuml | 4 +- source/specification/level-1/level-1.plantuml | 8 ++-- 5 files changed, 75 insertions(+), 23 deletions(-) create mode 100644 source/specification/level-1/coverage.plantuml diff --git a/source/conf.py b/source/conf.py index ce22855..21b42b4 100644 --- a/source/conf.py +++ b/source/conf.py @@ -35,6 +35,7 @@ # ones. extensions = [ "sphinxcontrib.plantuml", + "sphinx.ext.mathjax", ] # Add any paths that contain templates here, relative to this directory. diff --git a/source/specification/level-1/coverage.plantuml b/source/specification/level-1/coverage.plantuml new file mode 100644 index 0000000..a812428 --- /dev/null +++ b/source/specification/level-1/coverage.plantuml @@ -0,0 +1,38 @@ +@startuml +!include ../common.inc +skinparam linetype ortho + +package IVOA <> { + class TMOC +} + +package VODF { + package L1 { + class SpatialCoverage { + + r_fov : float + ..optional.. + + region : Region + } + + class TemporalCoverage { + + t_start + + t_stop + } + + class SpectralCoverage { + + energy_min + + energy_max + } + + Coverage *-- SpatialCoverage + Coverage *-- TemporalCoverage + Coverage *-- SpectralCoverage + TemporalCoverage -- IVOA.TMOC + SpatialCoverage -- IVOA.TMOC + + TemporalCoverage ..> OnTime + TemporalCoverage ..> Pointing + } +} + +@enduml diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index 42197ef..e82ea0a 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -9,12 +9,12 @@ of those events map to physical quantities. This data level may contain extra in the instrument pointing, provenance information, :term:`stable time intervals or instrumental good time intervals`, systematics error or quality estimation of the :term:`IRF`. It also covers related information such as time-series tables of data quality, instrumental or atmospheric conditions. -Level-1 data is assumed to be already *pre-processed* by the instrument that -produces it. The pre-processing must include all calibration and +Level-1 data products are assumed to be already *pre-processed* by the instrument that +produces them. The pre-processing must include all calibration and :term:`reconstruction` necessary to reduce the raw data of the instrument into a set of physical estimated parameters per detected particle. -.. note:: VODF Level-1 is equivalent to *data level 3 (DL3)* defined by CTAO, +.. tip:: VODF Level-1 is equivalent to *data level 3 (DL3)* defined by CTAO, also called "science-ready data". In CTAO, levels DL0-DL2 constitute the *raw* and *pre-processed* data levels that are out of scope for VODF. @@ -54,6 +54,12 @@ Data Releases TBD +Coverage +-------- + +.. uml:: coverage.plantuml + :caption: VODF **Level-1 Coverage** Data Model + EventList ---------- @@ -67,9 +73,11 @@ IRF :caption: VODF **Level-1 IRF** Data Model The :term:`IRF` contains the information necessary to map instrumental -:term:`reconstructed` parameters of the event to *physical* parameters, i.e. it -allows one to transform from a physical *flux* in a given space-time-spectral -interval into a predicted number of detected *counts* for a given instrument. +:term:`reconstructed ` parameters of the event to *physical* +parameters, i.e. it allows one to transform from a physical *flux* in a given +space-time-spectral interval into a predicted number of detected *counts* for a +given instrument. + .. tip:: @@ -80,30 +88,35 @@ interval into a predicted number of detected *counts* for a given instrument. (instrumental units), and the fit is performed on this transformed quantity by comparing the predicted to measured counts. The opposite process, *unfolding*, where instrumental uncertainties are removed by deconvolution - and the model is fit in physical units gives very unstable results when data - are noisy and contain background events. - + and the model is fit in physical units gives unstable results when data (or + the IRFs the are noisy. StandardIRF ~~~~~~~~~~~ In current instruments, the :term:`IRF` is typically decomposed into the -following components, which each provide a value as a function of a given point -in true (physical) coordinates, i.e. the spatial position in the FOV, time, -energy, or instrumental coordinates like zenith angle, azimuth, event -reconstruction type, etc. +following components: -Effective Collection Area (``EffectiveArea``) - Blah. +.. math:: + + R(E', {\vec{p'}} | E, \vec{p}, t) = + \underbrace{A_\text{eff}(E, \vec{p}, t)}_{{\text{Effective Area}}} + \cdot \overbrace{M(E' | E, \vec{p}, t)}^{{\text{Energy Migration}}} + \cdot \underbrace{\mathrm{PSF}(\vec{p'} | E, \vec{p}, t)}_{{\text{Point Spread Function}}}. + + +Effective Collection Area Function (``EffectiveArea``) + Given a set of physical parameters, provides the collection area of the + instrument, computed usually from detailed simulations. Point-Spread Function (``PSF``) Blah. -Energy Migration Matrix (``EnergyMigration``) +Energy Migration Function (``EnergyMigration``) Blah. -Background Rate (``BackgroundRate``) +Background Rate Function (``BackgroundRate``) The expected rate of background events (in counts/second). Often, the real rate is difficult to compute correctly without real data due to e.g. atmospheric uncertainties, and therefore it is important to note that it may diff --git a/source/specification/level-1/irf.plantuml b/source/specification/level-1/irf.plantuml index adc6bc1..b6b60bd 100644 --- a/source/specification/level-1/irf.plantuml +++ b/source/specification/level-1/irf.plantuml @@ -16,8 +16,8 @@ package VODF.L1 { IRF <|-- StandardIRF StandardIRF *-- EffectiveArea - StandardIRF *-- BackgroundRate + StandardIRF *-- "0..1" BackgroundRate StandardIRF *-- EnergyMigration - StandardIRF *-- PSF + StandardIRF *-- "0..1" PSF } diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index 0919d56..a070977 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -33,10 +33,8 @@ package VODF.L1 { class Observation #line.bold { + obs_id -- - ~ primary_particle_id - ~ temporal_coverage - ~ spatial_coverage - ~ energy_coverage + ~ coverage: Coverage + ~ primary_particle_id: int ~ ... } @@ -55,6 +53,8 @@ package VODF.L1 { Observation "1" --l-- "1" Instrument : used > Facility "1" -r-- "*" DataRelease + + ' Constituent parts of an observation Observation "1" o-- "1" Pointing Observation "1" o-- "1..*" OnTime From eacd8105e3995b63494f0311e713d593d7366f33 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 10:35:55 +0200 Subject: [PATCH 22/34] more text defining the IRF --- source/specification/level-1/index.rst | 51 ++++++++++++++++++++------ 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index e82ea0a..0bf0170 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -95,7 +95,22 @@ given instrument. StandardIRF ~~~~~~~~~~~ -In current instruments, the :term:`IRF` is typically decomposed into the +For VODF, we define a commonly used definition of the :term:`IRF`, which +separates the response :math:`\hat R` from the background rate :math:`B`. This +is convenient since :math:`\hat R` is usually computed from simulations, while +:math:`B` can be computed from observed data using blank fields. Then, the +predicted instrumental counts :math:`N` can be computed for a given flux +:math:`F` as: + +.. math:: + + N(\vec{p}', E' | \vec{p}, E) = \int d\Omega dE \; \hat{R}(\vec{p}',E'|\vec{p},E) \, F(\vec{p}, E) + \int d\Omega dE \; B(\vec{p}', E') + +where :math:`(\vec{p}, E)` are the *true* primary particle point of origin and +its energy, and :math:`(\vec{p}',E')` are the corresponding :term:`reconstructed +` quantities. The coordinate system for :math:`\vec p` is +usually represented in polar coordinates relative to the FOV center, though +other representations are possible. Then, we decompose :math:`R` into the following components: .. math:: @@ -108,22 +123,36 @@ following components: Effective Collection Area Function (``EffectiveArea``) Given a set of physical parameters, provides the collection area of the - instrument, computed usually from detailed simulations. + instrument, computed usually from detailed simulations as the ratio of the + number of detected events to the total simulated multiplied by the area over + which they were simulated, for given true position in the field of view and + true energy. Point-Spread Function (``PSF``) - Blah. + The probability to reconstruct an event a point :math:`\vec p'` in the FOV + if it had a true position :math:`\vec p`. Positional bias is ignored, + therefore it represents only the dispersion, i.e. the mean reconstructed + position is assumed equal to the true position. Energy Migration Function (``EnergyMigration``) - Blah. + The probability to reconstruct the energy as :math:`E'` for a given true + energy :math:`E`, including both dispersion and bias. This sometimes called + the *energy redistribution matrix*, or the *redistribution matrix file + (RMF)*. Background Rate Function (``BackgroundRate``) - The expected rate of background events (in counts/second). Often, the real - rate is difficult to compute correctly without real data due to e.g. - atmospheric uncertainties, and therefore it is important to note that it may - need to be calibrated using real data. I.e. the shape should be correct, but - the normalization may need to be refined. - - + The expected rate of background events (in counts/second) at a given point + :math:`\vec p` and energy `E`. Often, the real rate is difficult to compute + correctly without real data due to e.g. atmospheric uncertainties, and + therefore it is important to note that it may need to be calibrated using + real data. I.e. the shape should be correct, but the normalization may need + to be refined. + +.. note:: + + This decomposition ignores cross-terms, like the correlation between spectral + and spatial resolution, which can be important in some cases. Future versions + of VODF may include more detailed decompositions. OnTime ------ From 839dd6b97039846fcf1ee5a4ac5b260d4ed2eb24 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 10:50:11 +0200 Subject: [PATCH 23/34] cleanups to IRF --- source/specification/level-1/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index 0bf0170..c8b0fd6 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -118,29 +118,29 @@ following components: R(E', {\vec{p'}} | E, \vec{p}, t) = \underbrace{A_\text{eff}(E, \vec{p}, t)}_{{\text{Effective Area}}} \cdot \overbrace{M(E' | E, \vec{p}, t)}^{{\text{Energy Migration}}} - \cdot \underbrace{\mathrm{PSF}(\vec{p'} | E, \vec{p}, t)}_{{\text{Point Spread Function}}}. + \cdot \underbrace{P(\vec{p'} | E, \vec{p}, t)}_{{\text{Point Spread Function}}}. -Effective Collection Area Function (``EffectiveArea``) +Effective Collection Area Function (:math:`A_\mathrm{eff}`, ``EffectiveArea``) Given a set of physical parameters, provides the collection area of the instrument, computed usually from detailed simulations as the ratio of the number of detected events to the total simulated multiplied by the area over which they were simulated, for given true position in the field of view and true energy. -Point-Spread Function (``PSF``) +Point-Spread Function (:math:`P`, ``PSF``) The probability to reconstruct an event a point :math:`\vec p'` in the FOV if it had a true position :math:`\vec p`. Positional bias is ignored, therefore it represents only the dispersion, i.e. the mean reconstructed position is assumed equal to the true position. -Energy Migration Function (``EnergyMigration``) +Energy Migration Function (:math:`M`, ``EnergyMigration``) The probability to reconstruct the energy as :math:`E'` for a given true energy :math:`E`, including both dispersion and bias. This sometimes called the *energy redistribution matrix*, or the *redistribution matrix file (RMF)*. -Background Rate Function (``BackgroundRate``) +Background Rate Function (:math:`B`, ``BackgroundRate``) The expected rate of background events (in counts/second) at a given point :math:`\vec p` and energy `E`. Often, the real rate is difficult to compute correctly without real data due to e.g. atmospheric uncertainties, and From da279a1709459335765bf2936ac5adf796fed4cc Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 11:09:50 +0200 Subject: [PATCH 24/34] add a todo about even types / IRFs --- source/conf.py | 3 +++ source/specification/level-1/index.rst | 16 +++++++++++++--- source/specification/level-1/irf.plantuml | 3 +-- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/source/conf.py b/source/conf.py index 21b42b4..f034431 100644 --- a/source/conf.py +++ b/source/conf.py @@ -36,6 +36,7 @@ extensions = [ "sphinxcontrib.plantuml", "sphinx.ext.mathjax", + "sphinx.ext.todo", ] # Add any paths that contain templates here, relative to this directory. @@ -110,6 +111,8 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +# Show TODO entries. Disable this before release +todo_include_todos = True # ====================================================================== # Options for LaTeX docment output diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index c8b0fd6..193101b 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -76,8 +76,12 @@ The :term:`IRF` contains the information necessary to map instrumental :term:`reconstructed ` parameters of the event to *physical* parameters, i.e. it allows one to transform from a physical *flux* in a given space-time-spectral interval into a predicted number of detected *counts* for a -given instrument. - +given instrument. The IRF is often decomposed into a set of independent +``IRFComponents``, e.g. by separating spatial and spectral aspects. An IRF may +also vary in time, due to changing observation conditions, or instrumental +degradation. The assumption in VODF is that time variations are ignored and +therefore an :term :`observation` is broken into pieces where the IRF remains +stable, and residual variations are handled by adding instrumental parameters. .. tip:: @@ -95,7 +99,7 @@ given instrument. StandardIRF ~~~~~~~~~~~ -For VODF, we define a commonly used definition of the :term:`IRF`, which +For VODF, we provide a commonly used decomposition of the :term:`IRF` that separates the response :math:`\hat R` from the background rate :math:`B`. This is convenient since :math:`\hat R` is usually computed from simulations, while :math:`B` can be computed from observed data using blank fields. Then, the @@ -154,6 +158,12 @@ Background Rate Function (:math:`B`, ``BackgroundRate``) and spatial resolution, which can be important in some cases. Future versions of VODF may include more detailed decompositions. + +.. todo:: + + Discuss event types here? + + OnTime ------ diff --git a/source/specification/level-1/irf.plantuml b/source/specification/level-1/irf.plantuml index b6b60bd..2a2c061 100644 --- a/source/specification/level-1/irf.plantuml +++ b/source/specification/level-1/irf.plantuml @@ -10,8 +10,7 @@ package VODF.L1 { class EnergyMigration <> class PSF <> - IRF *-- "1..*" IRFComponent - + IRF *-- "0..*" IRFComponent IRF <|-- StandardIRF From 794e9981a55012537c82bc07db49233e26ddae66 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 11:11:19 +0200 Subject: [PATCH 25/34] fix typo --- source/specification/level-1/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index 193101b..70be950 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -92,8 +92,8 @@ stable, and residual variations are handled by adding instrumental parameters. (instrumental units), and the fit is performed on this transformed quantity by comparing the predicted to measured counts. The opposite process, *unfolding*, where instrumental uncertainties are removed by deconvolution - and the model is fit in physical units gives unstable results when data (or - the IRFs the are noisy. + and the model is fit in physical units gives unstable results when data or + IRFs contain instrumental or statistical noise. StandardIRF From 53fb258d2b61cf668fbf7728e99a94827019a9fd Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 11:12:35 +0200 Subject: [PATCH 26/34] PSF shouldn't be optional, even for spatial selection --- source/specification/level-1/irf.plantuml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specification/level-1/irf.plantuml b/source/specification/level-1/irf.plantuml index 2a2c061..948a33f 100644 --- a/source/specification/level-1/irf.plantuml +++ b/source/specification/level-1/irf.plantuml @@ -15,8 +15,8 @@ package VODF.L1 { IRF <|-- StandardIRF StandardIRF *-- EffectiveArea - StandardIRF *-- "0..1" BackgroundRate + StandardIRF *-- BackgroundRate StandardIRF *-- EnergyMigration - StandardIRF *-- "0..1" PSF + StandardIRF *-- PSF } From fda39dd2f37f1b6a97b040b31a9d5e086d719de3 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 11:34:54 +0200 Subject: [PATCH 27/34] improve event diagram --- .../specification/level-1/eventlist.plantuml | 32 +++++++++++++------ source/specification/level-1/level-1.plantuml | 2 +- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/source/specification/level-1/eventlist.plantuml b/source/specification/level-1/eventlist.plantuml index 8269bee..f6ca22d 100644 --- a/source/specification/level-1/eventlist.plantuml +++ b/source/specification/level-1/eventlist.plantuml @@ -4,20 +4,32 @@ package VODF.L1 { - class EventList + class EventList { + + collection_id + + obs_id + } class Event { - + ra_reco - + dec_reco - + time_reco - + energy_reco + + event_id: int64 + -- + + ra_reco: float32 + + dec_reco: float32 + + time_reco: TimeStamp + + energy_reco: float32 + ..optional.. + + event_type: int + + alt_reco: float32 + + az_reco: float32 } class SimulatedEvent { - + ra_true - + dec_true - + time_true - + energy_true - + particle_type_true + + alt_true: float32 + + az_true: float32 + + energy_true: float32 + + time_true: TimeStamp + + particle_id_true : ParticleID + ..optional.. + + ra_true: float32 + + dec_true: float32 } EventList "1" o-- "0..*" Event diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index a070977..18ff7d6 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -34,7 +34,7 @@ package VODF.L1 { + obs_id -- ~ coverage: Coverage - ~ primary_particle_id: int + ~ primary_particle_id: ParticleID ~ ... } From 25794c773ef37f10215d572ba9983288fb93b048 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 11:57:48 +0200 Subject: [PATCH 28/34] started to add PDGID, etc --- source/specification/core-concepts.rst | 39 +++++++++++++++++++ .../specification/level-1/eventlist.plantuml | 2 +- source/specification/level-1/level-1.plantuml | 2 +- 3 files changed, 41 insertions(+), 2 deletions(-) diff --git a/source/specification/core-concepts.rst b/source/specification/core-concepts.rst index 473c4f0..7b03d40 100644 --- a/source/specification/core-concepts.rst +++ b/source/specification/core-concepts.rst @@ -3,3 +3,42 @@ Core Concepts This describes the overall data model of VODF and how its component parts are inter-related. + +Data Levels +----------- + +.. todo:: + + Describe high-level relationship between L1 to L4 + +Common Types +------------ + +.. uml:: + + !include common.inc + class TimeStamp + + +PDGID +~~~~~ + +.. uml:: + + !include common.inc + class PDGID <> + + +Particle ids used in VODF shall follow the integer `https://particle.wiki/wiki/PDG_particle_numbering_scheme `_, e.g.: + + +.. csv-table:: Some example PDGIDs + :header: "Particle","ID" + :widths: 1,5 + + ":math:`\gamma`", 22 + ":math:`e-`", 11 + ":math:`p`", 2212 + ":math:`\nu_e`", 12 + ":math:`\nu_\mu`", 14 + ":math:`\nu_\tau`",16 diff --git a/source/specification/level-1/eventlist.plantuml b/source/specification/level-1/eventlist.plantuml index f6ca22d..ae79ac3 100644 --- a/source/specification/level-1/eventlist.plantuml +++ b/source/specification/level-1/eventlist.plantuml @@ -26,7 +26,7 @@ package VODF.L1 { + az_true: float32 + energy_true: float32 + time_true: TimeStamp - + particle_id_true : ParticleID + + particle_id_true : PDGID ..optional.. + ra_true: float32 + dec_true: float32 diff --git a/source/specification/level-1/level-1.plantuml b/source/specification/level-1/level-1.plantuml index 18ff7d6..5c375fb 100644 --- a/source/specification/level-1/level-1.plantuml +++ b/source/specification/level-1/level-1.plantuml @@ -34,7 +34,7 @@ package VODF.L1 { + obs_id -- ~ coverage: Coverage - ~ primary_particle_id: ParticleID + ~ primary_particle_id: PDGID ~ ... } From b3c6dcb1d873f8080dc9ba43a37094df9be5d5b8 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 12:00:05 +0200 Subject: [PATCH 29/34] fixed some typos --- source/specification/core-concepts.rst | 5 +++++ source/specification/level-1/index.rst | 6 +++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/source/specification/core-concepts.rst b/source/specification/core-concepts.rst index 7b03d40..976f3f9 100644 --- a/source/specification/core-concepts.rst +++ b/source/specification/core-concepts.rst @@ -19,6 +19,11 @@ Common Types !include common.inc class TimeStamp +Maps and N-Dimensional Arrays +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + PDGID ~~~~~ diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index 70be950..a09669b 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -3,7 +3,7 @@ ========= VODF Level-1 contains data products related to specific -:term:`observations`, and in particular to :term:`events` detected +:term:`observations `, and in particular to :term:`events` detected by a given instrument as well as :term:`IRF` that describe how the parameters of those events map to physical quantities. This data level may contain extra information on the instrument pointing, provenance information, :term:`stable time intervals or instrumental good time intervals`, systematics error or quality estimation of the :term:`IRF`. It also covers related information @@ -39,7 +39,7 @@ are not purely hardware, but a combination of hardware and software, and the details of the *low-level data processing changes the characteristics of the instrument*. With improvements to this low-level processing, the sensitivity, angular resolution, energy resolution, and other factors can change. A second -consequence of :term:`observations` being software-defined is that the +consequence of :term:`observations ` being software-defined is that the minimal duration is therefore up to the observatory. It can be directly related to one *data acquisition interval*, but can also be a subset or concatenation of many. @@ -80,7 +80,7 @@ given instrument. The IRF is often decomposed into a set of independent ``IRFComponents``, e.g. by separating spatial and spectral aspects. An IRF may also vary in time, due to changing observation conditions, or instrumental degradation. The assumption in VODF is that time variations are ignored and -therefore an :term :`observation` is broken into pieces where the IRF remains +therefore an :term:`observation` is broken into pieces where the IRF remains stable, and residual variations are handled by adding instrumental parameters. .. tip:: From 3ac2688119f35af0486734aacd9b82d618ea84d1 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 15:16:07 +0200 Subject: [PATCH 30/34] fix logo --- source/conf.py | 9 +++++++-- source/specification/level-1/index.rst | 2 +- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/source/conf.py b/source/conf.py index f034431..b6c5f86 100644 --- a/source/conf.py +++ b/source/conf.py @@ -86,9 +86,15 @@ }, "header_links_before_dropdown": 6, "announcement": "

This is an unreleased version, informaton may not be correct

", - "footer_start": ["copyright",], + "footer_start": [ + "copyright", + ], "footer_center": ["last-updated"], "footer_end": ["sphinx-version", "theme-version"], + "logo": { + "image_light": "source/_static/VODF-logo.png", + "image_dark": "source/_static/VODF-logo.png", + }, } html_context = { @@ -103,7 +109,6 @@ html_css_files = [ "custom.css", ] -html_logo = "_static/VODF-logo.svg" # Add any paths that contain custom static files (such as style sheets) here, diff --git a/source/specification/level-1/index.rst b/source/specification/level-1/index.rst index a09669b..1e5ed90 100644 --- a/source/specification/level-1/index.rst +++ b/source/specification/level-1/index.rst @@ -108,7 +108,7 @@ predicted instrumental counts :math:`N` can be computed for a given flux .. math:: - N(\vec{p}', E' | \vec{p}, E) = \int d\Omega dE \; \hat{R}(\vec{p}',E'|\vec{p},E) \, F(\vec{p}, E) + \int d\Omega dE \; B(\vec{p}', E') + \underbrace{N(\vec{p}', E' | \vec{p}, E)}_{Instrumental\ Counts} = \int d\Omega dE \; \hat{R}(\vec{p}',E'|\vec{p},E) \, \underbrace{F(\vec{p}, E)}_{Source\ Model} + \int d\Omega dE \; B(\vec{p}', E') where :math:`(\vec{p}, E)` are the *true* primary particle point of origin and its energy, and :math:`(\vec{p}',E')` are the corresponding :term:`reconstructed From 1dadd506f15a1bead06c68a48bf3c149bf441481 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 16:18:12 +0200 Subject: [PATCH 31/34] better layout --- source/specification/level-1/irf.plantuml | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/source/specification/level-1/irf.plantuml b/source/specification/level-1/irf.plantuml index 948a33f..69f24ac 100644 --- a/source/specification/level-1/irf.plantuml +++ b/source/specification/level-1/irf.plantuml @@ -10,13 +10,12 @@ package VODF.L1 { class EnergyMigration <> class PSF <> - IRF *-- "0..*" IRFComponent + IRF *-d- "0..*" IRFComponent + IRF <|-r---- StandardIRF - IRF <|-- StandardIRF - - StandardIRF *-- EffectiveArea - StandardIRF *-- BackgroundRate - StandardIRF *-- EnergyMigration - StandardIRF *-- PSF + StandardIRF *--- EffectiveArea + StandardIRF *--- BackgroundRate + StandardIRF *--- EnergyMigration + StandardIRF *--- PSF } From 1af9779fdf21064f02e291034c14c41d5759a0a7 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 16:18:20 +0200 Subject: [PATCH 32/34] remove comments --- source/conf.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/source/conf.py b/source/conf.py index b6c5f86..6df1208 100644 --- a/source/conf.py +++ b/source/conf.py @@ -72,11 +72,8 @@ version_match = "v" + release html_theme_options = { - # "logo_link": "", "github_url": "https://github.com/vodf/vodf-docs", "icon_links_label": "Quick Links", - # "show_nav_level": 4, - # "navigation_depth": 4, "use_edit_page_button": True, "navbar_align": "content", "navbar_end": ["version-switcher", "navbar-icon-links"], # "theme-switcher" @@ -92,6 +89,7 @@ "footer_center": ["last-updated"], "footer_end": ["sphinx-version", "theme-version"], "logo": { + "text":"VODF: Very-High-Energy Open Data Format", "image_light": "source/_static/VODF-logo.png", "image_dark": "source/_static/VODF-logo.png", }, From 63ffb96933a2fcbf5057363715372c4e32b33817 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 16:51:15 +0200 Subject: [PATCH 33/34] show MOC types in coverage --- source/specification/level-1/coverage.plantuml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/source/specification/level-1/coverage.plantuml b/source/specification/level-1/coverage.plantuml index a812428..29f2973 100644 --- a/source/specification/level-1/coverage.plantuml +++ b/source/specification/level-1/coverage.plantuml @@ -3,7 +3,10 @@ skinparam linetype ortho package IVOA <> { + + class SMOC class TMOC + class STMOC } package VODF { @@ -27,9 +30,14 @@ package VODF { Coverage *-- SpatialCoverage Coverage *-- TemporalCoverage Coverage *-- SpectralCoverage - TemporalCoverage -- IVOA.TMOC - SpatialCoverage -- IVOA.TMOC + TemporalCoverage *-d--- "0..1" IVOA.TMOC + TemporalCoverage *-d--- "0..1" IVOA.STMOC + SpatialCoverage *-d--- "0..1" IVOA.SMOC + SpatialCoverage *-d--- "0..1" IVOA.STMOC + + class OnTime <> + class Pointing <> TemporalCoverage ..> OnTime TemporalCoverage ..> Pointing } From 2f95bdbe3150746e23579fcaf3a03984f441b5a6 Mon Sep 17 00:00:00 2001 From: Karl Kosack Date: Wed, 30 Apr 2025 16:58:32 +0200 Subject: [PATCH 34/34] fix typo: text -> alt_text --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 6df1208..07c8fe2 100644 --- a/source/conf.py +++ b/source/conf.py @@ -89,7 +89,7 @@ "footer_center": ["last-updated"], "footer_end": ["sphinx-version", "theme-version"], "logo": { - "text":"VODF: Very-High-Energy Open Data Format", + "alt_text":"VODF: Very-High-Energy Open Data Format", "image_light": "source/_static/VODF-logo.png", "image_dark": "source/_static/VODF-logo.png", },