-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Changing docs for nfdata now that its a PyPI package
- Loading branch information
1 parent
ec01941
commit b2584b5
Showing
1 changed file
with
13 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,36 +1,28 @@ | ||
# Compiling data with the NanoFASE data module | ||
|
||
The *NanoFASE data module* is a collection of Python scripts that are used to compile input data for the model. It is recommended to use these scripts over and above manually compiling the NetCDF and constants namelist file required by the model, as the data module scripts take care of deriving a variety of [secondary derived variables](netcdf-namelist-input:secondary-derived-variables), amongst other reasons. | ||
The *NanoFASE data module* (`nfdata`) is a Python library that is used to compile input data for the model. It is recommended to use this library over and above manually compiling the NetCDF and constants namelist file required by the model, as the data module scripts take care of deriving a variety of [secondary derived variables](netcdf-namelist-input:secondary-derived-variables), amongst other reasons. | ||
|
||
## Getting started | ||
The library can be [found on GitHub](https://github.com/nerc-ceh/nfdata). | ||
|
||
```{note} | ||
The data module is currently only available as standalone scripts, rather than a Python package. This means that you must manually download the repository and set up a computational environment (install the correct packages) to be able to run the scripts, as detailed below. In the future, we will create a Python package from these scripts to ease this process. | ||
``` | ||
## Getting started | ||
|
||
Clone a copy of the repository from GitHub: | ||
The easiest way to use the library is to [install it from PyPI](https://pypi.org/project/nfdata/). For example, using pip: | ||
|
||
```bash | ||
$ git clone [email protected]:NERC-CEH/nanofase-data.git | ||
$ cd nanofase-data | ||
$ pip install nfdata | ||
``` | ||
|
||
Use Conda (or Mamba) to create a new environmental and install the required packages: | ||
|
||
```bash | ||
$ conda env create -f environment.yaml | ||
$ conda activate nanofase-data | ||
```{note} | ||
We are currently working on a Conda package for the library - watch this space! | ||
``` | ||
|
||
If you don't want to use Conda/Mamba, then the `environment.yaml` file lists the packages that need to be installed. | ||
|
||
## Basic usage | ||
|
||
The main script is `nanofase_data.py`: | ||
Once installed, the library can be run via the command line using the `nfdata` command: | ||
|
||
``` | ||
(nanofase-data) $ python nanofase_data.py --help | ||
usage: nanofase_data.py [-h] [--output OUTPUT] {create,edit,constants} file | ||
$ nfdata --help | ||
usage: nfdata [-h] [--output OUTPUT] {create,edit,constants} file | ||
Compile or edit data for the NanoFASE model. | ||
|
@@ -50,7 +42,7 @@ options: | |
Specifying the "create" option compiles a new NetCDF dataset and Fortran namelist constant file: | ||
|
||
```shell script | ||
(nanofase-data) $ python nanofase_data.py create /path/to/config.create.yaml | ||
$ nfdata create /path/to/config.create.yaml | ||
``` | ||
|
||
An annotated example config file is given: [`config.create.example.yaml`](https://github.com/NERC-CEH/nanofase-data/blob/develop/config.create.example.yaml). The file is quite self-explanatory, but a [full description is given below](nanofase-data:config). | ||
|
@@ -62,7 +54,7 @@ The two files will be output to the paths specified in the config file. | |
To edit an existing NetCDF dataset, specify the "edit" option: | ||
|
||
```shell script | ||
(nanofase-data) $ python nanofase_data.py edit /path/to/config.edit.yaml | ||
$ nfdata edit /path/to/config.edit.yaml | ||
``` | ||
|
||
An annotated example config file is given: [`config.edit.example.yaml`](https://github.com/NERC-CEH/nanofase-data/blob/develop/config.edit.example.yaml). This is similar (but not identical) in format to the creation config file, except only those variables you with to edit should be specified (all other variables are left as-is). Documentation for the config file is [provided below](nanofase-data:config). | ||
|
@@ -76,7 +68,7 @@ The Fortran namelist file cannot be edited using this method and you should inst | |
To simply convert a constants YAML file to a Fortran namelist file, you can use the `constants` option: | ||
|
||
```shell script | ||
(nanofase-data) $ python nanofase_data.py constants /path/to/constants.yaml -o /path/to/constants.nml | ||
$ nfdata constants /path/to/constants.yaml -o /path/to/constants.nml | ||
``` | ||
|
||
No config file is required. The location of the newly created constants file is given by the `-o` or `--output` argument. | ||
|