Merge pull request #6 from gregordecristoforo/main

Updates Readme and doctrisngs

README.md

@@ -9,6 +9,15 @@ dataset.
 
 xFELTOR is inspired by [xBOUT](https://github.com/boutproject/xBOUT) and uses currently some of its plotting functionality.
 
+## Why [xarray](https://xarray.pydata.org/en/stable/index.html)?
+
+[xarray](https://xarray.pydata.org/en/stable/index.html) is a powerful open-source python library which aims to provide Pandas-like labelling, visualization & analysis functionality for N-dimensional data. Some of the basic features are:
+* **Labelled multidimensional data**: xarray wraps numpy arrays with their `dims` as `DataArray`s.
+* **Clear syntax for operations**: xarray provides clearer and more general syntax containing less magic numbers than numpy 
+* **Lazy loading into memory**: never wastes RAM on unneeded values
+* **Plotting convenience**: xarray provides plotting functions (wrapping matplotlib) which automatically use an appropriate type of plot for the dimension of the data (1D, 2D etc.)
+
+For more information see the xarray [getting started guide](http://xarray.pydata.org/en/stable/getting-started-guide/why-xarray.html). Tom Nicholas' [presentation](https://github.com/TomNicholas/xBOUT--BOUT-workshop2019) about xarray and xBOUT is also a good place to start. 
 ## Installation
 
 Dev install:
@@ -18,11 +27,11 @@ cd xFELTOR
 pip install -e .
 ```
 
+
 ### Loading your data
 
 The function `open_feltordataset()` uses xarray & dask to collect FELTOR
-data spread across multiple NetCDF files into one contiguous xarray
-dataset.
+data into one xarray dataset. This can be either a single output file or multiple coherent files for restarted simulations.
 
 The data can be loaded with
 
@@ -32,7 +41,7 @@ ds = open_feltordataset("./run_dir*/*.nc")
 xFELTOR stores all variables from the FELTOR input file as attributes (xarray.Dataset.attrs).
 ### Plotting Methods
 
-In addition to the extensive functionalities provided by xarray, xFELTOR offers some usefull plotting methods. 
+In addition to the extensive functionalities provided by xarray, xFELTOR offers some useful plotting methods. 
 
 In order to plot the evolution of a 2D variable over time:
 ```python

xfeltor/feltordataarray.py

@@ -17,8 +17,8 @@ def __init__(self, da):
         self.data: xr.Dataset = da
 
     def __str__(self):
-        """
-        String representation of the FeltorDataset.
+        """String representation of the FeltorDataset.
+
         Accessed by print(ds.feltor)
         """
         styled = partial(prettyformat, indent=4, compact=False)

xfeltor/feltordataset.py

@@ -11,18 +11,15 @@
 
 @xr.register_dataset_accessor("feltor")
 class FeltorDatasetAccessor:
-    """
-    Contains FELTOR-specific methods to use on FELTOR datasets opened using
-    `open_feltordataset()`.
-
-    """
+    """Contains FELTOR-specific methods to use on FELTOR datasets opened using
+    `open_feltordataset()`."""
 
     def __init__(self, ds):
         self.data = ds
 
     def __str__(self):
-        """
-        String representation of the FeltorDataset.
+        """String representation of the FeltorDataset.
+
         Accessed by print(ds.feltor)
         """
         ds = self.data.copy()

xfeltor/load.py

@@ -10,16 +10,21 @@ def open_feltordataset(
     restart_indices: bool = False,
     **kwargs: dict,
 ) -> xr.Dataset:
-    """Load a dataset of FELTOR ouput files
+    """Loads FELTOR output into one xarray Dataset. Can load either a single
+    output file or multiple coherent files for restarted simulations.
 
     Parameters
     ----------
     datapath : str or (list or tuple of xr.Dataset), optional
         Path to the data to open. Can point to either a set of one or more *nc
         files.
     chunks : dict, optional
+        Dictionary with keys given by dimension names and values given by chunk sizes.
+        By default, chunks will be chosen to load entire input files into memory at once.
+        This has a major impact on performance: please see the full documentation for more details:
+        http://xarray.pydata.org/en/stable/user-guide/dask.html#chunking-and-performance
     restart_indices: bool, optional
-        if True, dublicate time steps from restared runs are kept
+        if True, duplicate time steps from restared runs are kept
     kwargs : optional
         Keyword arguments are passed down to `xarray.open_mfdataset`, which in
         turn passes extra kwargs down to `xarray.open_dataset`.
@@ -43,12 +48,9 @@ def open_feltordataset(
     _, index = np.unique(ds["time"], return_index=True)
 
     # store inputfile data in ds.attrs
-    tmp = ds.attrs["inputfile"]
-    tmp = tmp.replace("\n", "")
-    tmp = tmp.replace("\t", "")
-    result = json.loads(tmp)
+    input_variables = json.loads(ds.attrs["inputfile"])
 
-    for i in result:
-        ds.attrs[i] = result[i]
+    for i in input_variables:
+        ds.attrs[i] = input_variables[i]
 
     return ds.isel(time=index)