Skip to content

Docs for model_output_name need fixing #343

@bschroeter

Description

@bschroeter

Following a discussion with @abhaasgoyal this morning. It seems that there is an issue with the docs here.

### [meorg_output_name](#meorg_output_name)
: **Default:** unset, _optional key_. :octicons-dash-24: Chosen as the model name for one of the realisations, if the user wants to upload the Model Output to me.org for further analysis. The following workflow is executed:
1. A `model_output_name` is created using the format `<realisation_name>-<hash>`. Here, The `realisation_name` is determined where `meorg_output_name` is set as `true`.
**Note**: The `realisation_name` is set via [name](#name) if provided, otherwise the default repository name is used. A 6-character hash derived from `realisations`, `model_profile_id` and `$USER` is appended at the end. The hash is used to minimise name conflicts for different users' needs.
**Note**: In case `model_output_name` already exists on `me.org`, the files within that model output are deleted. This is done to send a fresh set of benchmarking results for analysis, ensuring that the user can re-run `benchcab` without any issues.
2. The following settings are taken by default for the model output:
* Model Profile - `CABLE`
* State Selection - `default`
* Parameter Selection - `automated`
* Bundled experiments - `true`
* Comments - `none`
3. Depending on the fluxsite [`experiment`](#`experiment`), `benchcab` will do the following:
- Add the correponding experiment to model output.
- Associate the experiment with base benchmark (already stored in `me.org`), and other listed realisations (since they share the same experiment).
4. Run the analysis, and provide a link to the user to check status.
The model output name should also follow the Github issue branch format (i.e. it should start with a digit, with words separated by dashes). Finally, the maximum number of characters allowed for `meorg_output_name` is 50.
This key is _optional_. No default.
```yaml
realisations:
- repo:
git:
branch: 123-my-branch
meorg_output_name: True
- repo:
git:
branch: 456-my-branch
```
### [name](#name)

Here is how I understand it.

  1. model_output_name is indented too far, putting it in the git section of a repo, when it should be at the same level as git.
  2. There needs to be more descriptive text to tell the user exactly what is expected in terms of syntax.
  3. There needs to be an explicit (admonition box?) telling the user that ONLY ONE realisation can feature the model_output_name key.
  4. model_output_name requires the name key to be set if not inferred from the branch?
  5. model_output_name is a boolean value, switching it on enables the meorg transfer.

Some of this may be briefly described in the text, but can be made clearer.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions