From fc8fbbbebff613400ab16d6278921a362c181368 Mon Sep 17 00:00:00 2001 From: Marco Donadoni Date: Thu, 8 Feb 2024 12:07:07 +0100 Subject: [PATCH] refactor(docs): move from reST to Markdown (#17) Convert docs from reStructuredText to Markdown so that the changelog file is compatible with Release Please. --- AUTHORS.md | 10 +++ AUTHORS.rst | 11 ---- README.md | 151 +++++++++++++++++++++++++++++++++++++++++++++ README.rst | 172 ---------------------------------------------------- 4 files changed, 161 insertions(+), 183 deletions(-) create mode 100644 AUTHORS.md delete mode 100644 AUTHORS.rst create mode 100644 README.md delete mode 100644 README.rst diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..85e21a7 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,10 @@ +# Authors + +The list of contributors in alphabetical order: + +- [Giuseppe Steduto](https://orcid.org/0009-0002-1258-8553) +- [Kati Lassila-Perini](https://orcid.org/0000-0002-5502-1795) +- [Radovan Lascsak](https://orcid.org/0000-0002-8412-5702) +- [Ronald Dobos](https://orcid.org/0000-0003-2914-000X) +- [Tibor Simko](https://orcid.org/0000-0001-7202-5803) +- [Vladyslav Moisieienkov](https://orcid.org/0000-0001-9717-0775) diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index b135c53..0000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,11 +0,0 @@ -Authors -======= - -The list of contributors in alphabetical order: - -- `Giuseppe Steduto `_ -- `Kati Lassila-Perini `_ -- `Radovan Lascsak `_ -- `Ronald Dobos `_ -- `Tibor Simko `_ -- `Vladyslav Moisieienkov `_ diff --git a/README.md b/README.md new file mode 100644 index 0000000..8a97b91 --- /dev/null +++ b/README.md @@ -0,0 +1,151 @@ +# REANA example - CMS dimuon mass spectrum + +[![image](https://www.reana.io/static/img/badges/launch-on-reana-at-cern.svg)](https://reana.cern.ch/launch?url=https%3A%2F%2Fgithub.com%2Freanahub%2Freana-demo-cms-dimuon-mass-spectrum&name=reana-demo-cms-dimuon-mass-spectrum) + +## About + +This REANA reproducible analysis example demonstrates the computation of the invariant +mass spectrum of two muon final states with CMS Open Data. It is based on the +[original code](http://opendata.cern.ch/record/5001) from the +[CERN Open Data portal](http://opendata.cern.ch/). + +## Analysis structure + +Making a research data analysis reproducible basically means to provide "runnable +recipes" addressing (1) where is the input data, (2) what software was used to analyse +the data, (3) which computing environments were used to run the software and (4) which +computational workflow steps were taken to run the analysis. This will permit to +instantiate the analysis on the computational cloud and run the analysis to obtain (5) +output results. + +### 1. Input data + +The `datasets` directory contains files with the information about locations of the +collision datasets and the list of validated runs that will be used in the analysis. + +### 2. Analysis code + +The analysis code is located in the in `src` directory and in `demoanalyzer_cfg.py` file. + +### 3. Compute environment + +In order to be able to rerun the analysis even several years in the future, we need to +"encapsulate the current compute environment", for example to freeze the software package +versions our analysis is using. We shall achieve this by preparing a +[Docker](https://www.docker.com) container image for our analysis steps. + +This example runs within the [CMSSW](http://cms-sw.github.io) analysis framework that was +packaged for Docker in [clelange/cmssw](https://hub.docker.com/r/clelange/cmssw/). + +### 4. Analysis workflow + +The computational workflow is essentially sequential in nature. We can use the REANA +serial workflow engine and represent the analysis workflow as follows: + +```console + START + | + | + V ++-----------------------------------------+ +| (1) scram b | +| | ++-----------------------------------------+ + | + | + V ++-----------------------------------------+ +| (2) demoanalyzer_cfg.py | <-- datasets +| | ++-----------------------------------------+ + | + | DoubleMu.root + | + V + STOP +``` + +### 5. Output results + +The run will create DoubleMu.root output file in the [ROOT](https://root.cern.ch/) format +that contains output histograms, for example: + +![](https://github.com/reanahub/reana-demo-cms-dimuon-mass-spectrum/blob/master/docs/plot_GMmass.png?raw=true) + +## Running the example on REANA cloud + +There are two ways to execute this analysis example on REANA. + +If you would like to simply launch this analysis example on the REANA instance at CERN +and inspect its results using the web interface, please click on the following badge: + +[![image](https://www.reana.io/static/img/badges/launch-on-reana-at-cern.svg)](https://reana.cern.ch/launch?url=https%3A%2F%2Fgithub.com%2Freanahub%2Freana-demo-cms-dimuon-mass-spectrum&name=reana-demo-cms-dimuon-mass-spectrum) + +If you would like a step-by-step guide on how to use the REANA command-line client to +launch this analysis example, please read on. + +We start by creating a [reana.yaml](reana.yaml) file describing the above analysis +structure with its inputs, code, runtime environment, computational workflow steps and +expected outputs: + +```yaml +version: 0.6.0 +inputs: + files: + - BuildFile.xml + - demoanalyzer_cfg.py + directories: + - datasets + - python + - src +workflow: + type: serial + specification: + steps: + - name: demoanalyzer + environment: 'docker.io/cmsopendata/cmssw_5_3_32' + commands: + - > + source /opt/cms/cmsset_default.sh + && scramv1 project CMSSW CMSSW_5_3_32 + && cd CMSSW_5_3_32/src + && eval `scramv1 runtime -sh` + && mkdir reana-demo-cms-dimuon-mass-spectrum + && cd reana-demo-cms-dimuon-mass-spectrum + && mkdir DimuonSpectrum2011 + && cd DimuonSpectrum2011 + && cp -r ../../../../datasets ../../../../python ../../../../src ../../../../BuildFile.xml ../../../../demoanalyzer_cfg.py . + && scram b + && cmsRun ./demoanalyzer_cfg.py +outputs: + files: + - CMSSW_5_3_32/src/reana-demo-cms-dimuon-mass-spectrum/DimuonSpectrum2011/DoubleMu.root +``` + +We can now install the REANA command-line client, run the analysis and download the +resulting ROOT file containing plots: + +```console +$ # create new virtual environment +$ virtualenv ~/.virtualenvs/myreana +$ source ~/.virtualenvs/myreana/bin/activate +$ # install REANA client +$ pip install reana-client +$ # connect to some REANA cloud instance +$ export REANA_SERVER_URL=https://reana.cern.ch/ +$ export REANA_ACCESS_TOKEN=XXXXXXX +$ # create new workflow +$ reana-client create -n my-analysis +$ export REANA_WORKON=my-analysis +$ # upload input code and data to the workspace +$ reana-client upload +$ # start computational workflow +$ reana-client start +$ # ... should be finished in about 1 minute +$ reana-client status +$ # download output root file with generated plots +$ reana-client download +``` + +Please see the [REANA-Client](https://reana-client.readthedocs.io/) documentation for +more detailed explanation of typical `reana-client` usage scenarios. diff --git a/README.rst b/README.rst deleted file mode 100644 index 7cbda60..0000000 --- a/README.rst +++ /dev/null @@ -1,172 +0,0 @@ -========================================== - REANA example - CMS dimuon mass spectrum -========================================== - -.. image:: https://www.reana.io/static/img/badges/launch-on-reana-at-cern.svg - :target: https://reana.cern.ch/launch?url=https%3A%2F%2Fgithub.com%2Freanahub%2Freana-demo-cms-dimuon-mass-spectrum&name=reana-demo-cms-dimuon-mass-spectrum - -About -====== - -This REANA reproducible analysis example demonstrates the computation of the -invariant mass spectrum of two muon final states with CMS Open Data. -It is based on the `original code `_ from -the `CERN Open Data portal `_. - -Analysis structure -=================== - -Making a research data analysis reproducible basically means to provide -"runnable recipes" addressing (1) where is the input data, (2) what software was -used to analyse the data, (3) which computing environments were used to run the -software and (4) which computational workflow steps were taken to run the -analysis. This will permit to instantiate the analysis on the computational -cloud and run the analysis to obtain (5) output results. - -1. Input data -------------- - -The ``datasets`` directory contains files with the information about locations -of the collision datasets and the list of validated runs that will be used in -the analysis. - -2. Analysis code ----------------- - -The analysis code is located in the in ``src`` directory and in -``demoanalyzer_cfg.py`` file. - -3. Compute environment ----------------------- - -In order to be able to rerun the analysis even several years in the future, we -need to "encapsulate the current compute environment", for example to freeze the -software package versions our analysis is using. We shall achieve this by -preparing a `Docker `_ container image for our analysis -steps. - -This example runs within the `CMSSW `_ analysis -framework that was packaged for Docker in `clelange/cmssw -`_. - -4. Analysis workflow --------------------- - -The computational workflow is essentially sequential in nature. We can use the -REANA serial workflow engine and represent the analysis workflow as follows: - -.. code-block:: console - - START - | - | - V - +-----------------------------------------+ - | (1) scram b | - | | - +-----------------------------------------+ - | - | - V - +-----------------------------------------+ - | (2) demoanalyzer_cfg.py | <-- datasets - | | - +-----------------------------------------+ - | - | DoubleMu.root - | - V - STOP - -5. Output results ------------------ - -The run will create DoubleMu.root output file in the `ROOT -`_ format that contains output histograms, for example: - -.. figure:: https://github.com/reanahub/reana-demo-cms-dimuon-mass-spectrum/blob/master/docs/plot_GMmass.png?raw=true - :alt: plot_GMmass.png - :align: center - -Running the example on REANA cloud -================================== - -There are two ways to execute this analysis example on REANA. - -If you would like to simply launch this analysis example on the REANA instance -at CERN and inspect its results using the web interface, please click on -the following badge: - -.. image:: https://www.reana.io/static/img/badges/launch-on-reana-at-cern.svg - :target: https://reana.cern.ch/launch?url=https%3A%2F%2Fgithub.com%2Freanahub%2Freana-demo-cms-dimuon-mass-spectrum&name=reana-demo-cms-dimuon-mass-spectrum - -| - -If you would like a step-by-step guide on how to use the REANA command-line -client to launch this analysis example, please read on. - -We start by creating a `reana.yaml `_ file describing the above -analysis structure with its inputs, code, runtime environment, computational -workflow steps and expected outputs: - -.. code-block:: yaml - version: 0.6.0 - inputs: - files: - - BuildFile.xml - - demoanalyzer_cfg.py - directories: - - datasets - - python - - src - workflow: - type: serial - specification: - steps: - - name: demoanalyzer - environment: 'docker.io/cmsopendata/cmssw_5_3_32' - commands: - - > - source /opt/cms/cmsset_default.sh - && scramv1 project CMSSW CMSSW_5_3_32 - && cd CMSSW_5_3_32/src - && eval `scramv1 runtime -sh` - && mkdir reana-demo-cms-dimuon-mass-spectrum - && cd reana-demo-cms-dimuon-mass-spectrum - && mkdir DimuonSpectrum2011 - && cd DimuonSpectrum2011 - && cp -r ../../../../datasets ../../../../python ../../../../src ../../../../BuildFile.xml ../../../../demoanalyzer_cfg.py . - && scram b - && cmsRun ./demoanalyzer_cfg.py - outputs: - files: - - CMSSW_5_3_32/src/reana-demo-cms-dimuon-mass-spectrum/DimuonSpectrum2011/DoubleMu.root - -We can now install the REANA command-line client, run the analysis and download -the resulting ROOT file containing plots: - -.. code-block:: console - - $ # create new virtual environment - $ virtualenv ~/.virtualenvs/myreana - $ source ~/.virtualenvs/myreana/bin/activate - $ # install REANA client - $ pip install reana-client - $ # connect to some REANA cloud instance - $ export REANA_SERVER_URL=https://reana.cern.ch/ - $ export REANA_ACCESS_TOKEN=XXXXXXX - $ # create new workflow - $ reana-client create -n my-analysis - $ export REANA_WORKON=my-analysis - $ # upload input code and data to the workspace - $ reana-client upload - $ # start computational workflow - $ reana-client start - $ # ... should be finished in about 1 minute - $ reana-client status - $ # download output root file with generated plots - $ reana-client download - -Please see the `REANA-Client `_ -documentation for more detailed explanation of typical ``reana-client`` usage -scenarios.