@@ -9,6 +9,69 @@ input parameters.
99An Application Package can have, and usually does have, * input parameters*
1010defined types and default values, which can be set by the caller when running
1111the package. xcengine automatically generates these parameters from variables
12- in the notebook. Any variable to be used as a parameter
12+ in the notebook. Any variable to be used as a parameter must be defined
13+ in the ** parameters cell** of the notebook. You can only have one parameters
14+ cell in a notebook, and it is strongly advised that the parameters cell appear
15+ ** as early as possible** in the notebook.
1316
14- ## Configuring xcengine
17+ You turn a normal code cell into a parameters cell by adding a tag called
18+ ** parameters** to it in the Jupyter Lab using the Property Inspector.
19+ (The Property Inspector can be opened by clicking the gear icon at the top
20+ right of the Jupyter Lab window.)
21+
22+ ![ Property inspector] ( images/property-inspector.png )
23+
24+ You can define as many parameters as you like in the property cell. The
25+ values you assign to them will be used as the default values for these
26+ parameters when xcengine generates the Application Package.
27+
28+ ## Configuring xcengine
29+
30+ As well as parameters, the parameters cell can contain an ** xcengine
31+ configuration dictionary** . This is a Python dictionary with the special
32+ name ` xcengine_config ` . Available configuration settings are:
33+
34+ - ` workflow_id ` : a string identifier for the workflow in your Application
35+ Package. The runner or Application Package platform can use this
36+ identifier to refer to you Application Package. By default, the name
37+ of the notebook (without the ` .ipynb ` suffix) is used.
38+ - ` environment_file ` : the name of a YAML file defining a [ conda
39+ environment] ( https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html )
40+ (these are often called ` environment.yml ` ). If an environment file is not
41+ specified in the notebook or on the command line, xcetool will try to
42+ deduce the environment automatically. This cannot be done 100% reliably,
43+ so it is ** strongly recommended** to provide an environment file.
44+ - ` container_image_tag ` : the tag applied to the Docker container image that
45+ xcengine builds. If you plan to push the image to a public registry,
46+ you can enter the final registry tag here and push the image once it's
47+ been built by xcengine. If no tag is specified, xcengine will create one
48+ based on the current date and time.
49+
50+ Some of these configuration settings can also be set on the command line.
51+
52+ ## Dataset output
53+
54+ ### Selecting datasets for output
55+
56+ No additional code or configuration is needed for datasets to be written from
57+ Application Packages or served when the container image is run in xcube
58+ Server/Viewer mode. xcengine will automatically output or serve any instance
59+ of ` xarray.DataSet ` which is in scope when the notebook's code has finished
60+ executing. If you're created some datasets which you * don't* wish to be
61+ written, you can use the Python
62+ [ ` del ` statement] ( https://docs.python.org/3/reference/simple_stmts.html#the-del-statement )
63+ to delete them at the end of the notebook to remove them e.g.
64+
65+ ``` python
66+ del my_temporary_dataset
67+ ```
68+
69+ ### Setting dataset output type
70+
71+ By default, all ` xarray.DataSet ` instances are written as Zarr. But you can
72+ force them to be written as NetCDF by setting an attribute on the dataset,
73+ like this:
74+
75+ ``` python
76+ my_dataset.attrs[" xcengine_output_format" = " netcdf"
77+ ```
0 commit comments