Skip to content

Commit

Permalink
Documentation language edit /spell check (#871)
Browse files Browse the repository at this point in the history 
* First iteration of spell check

* Spell check for setup

* physics model spell check

* Add commonstatsmethods language check

* Finish spellcheck part 3-4-5

* Fixing Combine small caps text in docs
  • Loading branch information
@adewit
adewit authored Dec 14, 2023
1 parent f27aa02 commit 598297d
Show file tree
Hide file tree
Showing 15 changed files with 777 additions and 775 deletions.
20 changes: 10 additions & 10 deletions contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing

Contributions to combine of all sizes, from minor documentation updates to big code improvements, are welcome and encouraged.
Contributions to <span style="font-variant:small-caps;">Combine</span> of all sizes, from minor documentation updates to big code improvements, are welcome and encouraged.

To ensure good development of the tool, we try to coordinate contributions.
However, we are happy to help overcome any steps that may pose issues for contributors.
Expand Down Expand Up @@ -42,19 +42,19 @@ ensure `flake8` and `black` are installed:
and then from the main directory of this repository run


flake8:
`flake8`:
```
flake8 .
```

and black:
and `black`:

```
black -l 160 --check --diff .
```

If you'd like to see the details of the configuration `flake8` is using, check the `.flake8` file in the main directory.
The black linting uses the default [black style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html) (for v23.3.0), with only the command line options shown above.
The `black` linting uses the default [black style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html) (for v23.3.0), with only the command line options shown above.


## Updating Documentation
Expand All @@ -65,7 +65,7 @@ For that reason, whenever you make a change you should consider whether this req
If the change is user-facing it almost certainly does require a documentation update.

Documentation is **very important** to us.
Therefore, we will be picky and make sure it is done well!
Therefore, we will be meticulous and make sure it is done well!
However, we don't want to put extra burden on you, so we are happy to help and will make our own edits and updates to improve the documentation of your change.

We appreciate you putting in some effort and thought to ensure:
Expand All @@ -76,7 +76,7 @@ We appreciate you putting in some effort and thought to ensure:

### Technical details of the documentation

We use [mkdocs](www.mkdocs.org) to produce the static website that documents combine.
We use [mkdocs](www.mkdocs.org) to produce the static website that documents <span style="font-variant:small-caps;">Combine</span>.

The documentation files are all under the `docs/` folder.
Which pages get included in the site, and other configuration details are set in the `mkdocs.yml` file.
Expand All @@ -97,17 +97,17 @@ mkdocs serve

from the main repository directory. mkdocs will then print a link you can open to check the page generated in your browser.

**NOTE:** mkdocs builds which use internal links (or images etc) with absolute paths will work for local deployment, but will break when deployed to the public documentations pages.
Please ensure you use relative paths. Currently, this is the only known feature where the behvaiour differs between local mkdocs and public pages deployment.
**NOTE:** mkdocs builds that use internal links (or images, etc.) with absolute paths will work for local deployment, but will break when deployed to the public documentations pages.
Please ensure you use relative paths. Currently, this is the only known feature where the behvaiour differs between local mkdocs and public page deployment.
If you'd like to test the deployment directly, the suggested method is to set up a docs page using your personal github account; this should mimic the exact settings of the official page.

## Big Contributions

We welcome large contributions to combine.
We welcome large contributions to <span style="font-variant:small-caps;">Combine</span>.
Note, however, that we also follow long term planning, and there is a dedicated group stewarding the overall direction and development of the code.

This means that the code development should fit in with our long term vision;
if you have an idea for a big improvement or change it will be most efficient if you [contact us](mailto:[email protected]) first, in order to ensure that we can integrate it as seemlessly as possible into our plans.
if you have an idea for a big improvement or change it will be most efficient if you [contact us](mailto:[email protected]) first, in order to ensure that we can integrate it as seamlessly as possible into our plans.
This will simplify any potential conflicts when you make your pull request.

## Requested Contributions
Expand Down
60 changes: 32 additions & 28 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

These pages document the
[RooStats](https://twiki.cern.ch/twiki/bin/view/RooStats/WebHome) /
[RooFit](https://root.cern.ch/roofit) - based software tools used for
statistical analysis within the [Higgs PAG](HiggsWG) - **combine**.
[RooFit](https://root.cern.ch/roofit) - based software tool used for
statistical analysis within the CMS experiment - <span style="font-variant:small-caps;">Combine</span>. Note that while this tool was originally developed in the [Higgs PAG](HiggsWG), its usage is now widespread within CMS.

Combine provides a command line interface to many different statistical techniques available inside RooFit/RooStats used widely inside CMS.
<span style="font-variant:small-caps;">Combine</span> provides a command-line interface to many different statistical techniques, available inside RooFit/RooStats, that are used widely inside CMS.

The package exists in GIT under [https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit)
The package exists on GitHub under [https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit)

For more information about GIT and its usage in CMS, see [http://cms-sw.github.io/cmssw/faq.html](http://cms-sw.github.io/cmssw/faq.html)
For more information about Git, GitHub and its usage in CMS, see [http://cms-sw.github.io/cmssw/faq.html](http://cms-sw.github.io/cmssw/faq.html)

The code can be checked out from GIT and compiled on top of a CMSSW release that includes a recent RooFit/RooStats
The code can be checked out from GitHub and compiled on top of a CMSSW release that includes a recent RooFit/RooStats

# Installation instructions

Expand All @@ -22,17 +22,17 @@ Earlier versions are not guaranteed to follow the standard.
## Within CMSSW (recommended for CMS users)

The instructions below are for installation within a CMSSW environment. For end
users that don't need to commit or do any development, the following recipes
users that do not need to commit or do any development, the following recipes
should be sufficient. To choose a release version, you can find the latest
releases on github under
[https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/releases](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/releases)

### Combine v9 - recommended version

The nominal installation method is inside CMSSW. The current release targets
CMSSW `11_3_X` series because this release has both python2 and python3 ROOT
bindings, allowing a more gradual migration of user code to python3. Combine is
fully python3-compatible and can work also in 12_X releases.
the CMSSW `11_3_X` series because this release has both python2 and python3 ROOT
bindings, allowing a more gradual migration of user code to python3. <span style="font-variant:small-caps;">Combine</span> is
fully python3-compatible and, with some adaptations, can also work in 12_X releases.

```sh
cmsrel CMSSW_11_3_4
Expand Down Expand Up @@ -99,11 +99,11 @@ scramv1 b clean; scramv1 b # always make a clean build
## Standalone compilation

The standalone version can be easily compiled using
[cvmfs](https://cernvm.cern.ch/fs/) as it relies on dependencies which are
[cvmfs](https://cernvm.cern.ch/fs/) as it relies on dependencies that are
already installed at `/cvmfs/cms.cern.ch/`. Access to `/cvmfs/cms.cern.ch/` can
be obtained from lxplus machines or via `CernVM`. See [CernVM](CernVM.md) for
further details on the latter. In case you do not want to use the `cvmfs`
area, you will need to adapt the location of the dependencies listed in both
area, you will need to adapt the locations of the dependencies listed in both
the `Makefile` and `env_standalone.sh` files.

```
Expand All @@ -114,18 +114,20 @@ cd HiggsAnalysis/CombinedLimit/
make -j 4
```

You will need to source `env_standalone.sh` each time you want to use the package, or add it to your login.
You will need to source `env_standalone.sh` each time you want to use the package, or add it to your login environment.

### Standalone compilation with LCG
For compilation outside of CMSSW, for example to use ROOT versions not yet available in CMSSW, one can compile against LCG releases. The current default is to compile with LCG_102 which contains ROOT 6.26:
For compilation outside of CMSSW, for example to use ROOT versions not yet available in CMSSW, one can compile against LCG releases. The current default is to compile with LCG_102, which contains ROOT 6.26:
```sh
git clone https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit.git HiggsAnalysis/CombinedLimit
cd HiggsAnalysis/CombinedLimit
source env_lcg.sh
make LCG=1 -j 8
```
To change the LCG version, edit `env_lcg.sh`. The resulting binaries can be relocated (e.g. for use in a
batch job) if the following files are included in the job tarball:
To change the LCG version, edit `env_lcg.sh`.

The resulting binaries can be moved for use in a
batch job if the following files are included in the job tarball:
```sh
tar -zcf Combine_LCG_env.tar.gz build interface src/classes.h --exclude=obj
```
Expand All @@ -148,40 +150,42 @@ conda activate combine
make CONDA=1 -j 8
```

Using combine from then on should only require sourcing the conda environment
Using <span style="font-variant:small-caps;">Combine</span> from then on should only require sourcing the conda environment
```
conda activate combine
```

**Note:** on OS X, `combine` can only accept workspaces, so run `text2workspace.py` first.
This is due to some ridiculous issue with child processes and `LD_LIBRARY_PATH` (see note in Makefile)
**Note:** on OS X, <span style="font-variant:small-caps;">Combine</span> can only accept workspaces, so run `text2workspace.py` first.
This is due to an issue with child processes and `LD_LIBRARY_PATH` (see note in Makefile)

# What has changed between tags?

You can generate a diff of any two tags (eg for `v7.0.8` and `v7.0.6`) by using following the url:
You can generate a diff of any two tags (eg for `v9.1.0` and `v9.0.0`) by using the following url:

[https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/compare/v7.0.6...v7.0.7](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/compare/v7.0.6...v7.0.7)
[https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/compare/v9.0.0...v9.1.0](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/compare/v9.0.0...v9.1.0)

Replace the tag names in the url to any tags you which to compare.
Replace the tag names in the url to any tags you would like to compare.

# For developers

We use the _Fork and Pull_ model for development: each user creates a copy of the repository on github, commits their requests there and then sends pull requests for the administrators to merge.
We use the _Fork and Pull_ model for development: each user creates a copy of the repository on GitHub, commits their requests there, and then sends pull requests for the administrators to merge.

_Prerequisites_

1. Register on github, as needed anyway for CMSSW development: [http://cms-sw.github.io/cmssw/faq.html](http://cms-sw.github.io/cmssw/faq.html)
1. Register on GitHub, as needed anyway for CMSSW development: [http://cms-sw.github.io/cmssw/faq.html](http://cms-sw.github.io/cmssw/faq.html)

2. Register your SSH key on GitHub: [https://help.github.com/articles/generating-ssh-keys](https://help.github.com/articles/generating-ssh-keys)

2. Register your SSH key on github: [https://help.github.com/articles/generating-ssh-keys](https://help.github.com/articles/generating-ssh-keys) 1 Fork the repository to create your copy of it: [https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/fork](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/fork) (more documentation at [https://help.github.com/articles/fork-a-repo](https://help.github.com/articles/fork-a-repo) )
3. Fork the repository to create your copy of it: [https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/fork](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/fork) (more documentation at [https://help.github.com/articles/fork-a-repo](https://help.github.com/articles/fork-a-repo) )

You will now be able to browse your fork of the repository from [https://github.com/your-github-user-name/HiggsAnalysis-CombinedLimit](https://github.com/your-github-user-name/HiggsAnalysis-CombinedLimit)

We strongly encourage you to contribute any developments you make back into the main repository.
We strongly encourage you to contribute any developments you make back to the main repository.
See [contributing.md](https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit/blob/main/contributing.md) for details about contributing.

# Combine Tool
# CombineHarvester/CombineTools

An additional tool for submitting combine jobs to batch/crab, developed originally for HiggsToTauTau. Since the repository contains a certain amount of analysis-specific code, the following scripts can be used to clone it with a sparse checkout for just the core [`CombineHarvester/CombineTools`](https://github.com/cms-analysis/CombineHarvester/blob/master/CombineTools/) subpackage, speeding up the checkout and compile times:
CombineTools is an additional tool for submitting <span style="font-variant:small-caps;">Combine</span> jobs to batch systems or crab, which was originally developed in the context of Higgs to tau tau analyses. Since the repository contains a certain amount of analysis-specific code, the following scripts can be used to clone it with a sparse checkout for just the core [`CombineHarvester/CombineTools`](https://github.com/cms-analysis/CombineHarvester/blob/master/CombineTools/) subpackage, speeding up the checkout and compile times:

git clone via ssh:

Expand Down
Loading

0 comments on commit 598297d

Please sign in to comment.