Documentation suggestions (pain points)

[eldobbins]

@kwilcox asked me to let him know where documentation would be helpful. If it's OK, I'd like to track it here.

First up, Installation. For instance, I did:

conda create -n pyocean pip
source activate pyocean
git clone https://github.com/pyoceans/pocean-core
cd pocean-core
conda install --file requirements.txt -c conda-forge
pip install -e ~/Desktop/code/pocean-core

[eldobbins]

dimension names are fixed, which is OK because CF documentation states: "This convention does not standardize any variable or dimension names". Must be x,y,z,t. But maybe need to adjust the incoming data.

[eldobbins]

Some attributes seem to be defined by these routines. Are they overwriting the ones I define?

[kwilcox]

@eldobbins Good call on the axes naming, this needs to be documented:

There is actually a way around the fixed dimension names. You can pass an axes mapping to many of the pocean functions if you don't want to use the predefined x, y, z, t, obs, profile, trajectory.

For example:

axes = {
    't': 'time',
    'x': 'lon',
    'y': 'lat',
    'sample': 'obs',
}

ncd = IncompleteMultidimensionalTrajectory.from_dataframe(df, axes=axes, output=somefile)

Will make a file with the dimensions/variables named time, lon, lat and obs. It is assumed each axes in the mapping is a column in df. Code that overwrite the defaul axes with the provided mapping: https://github.com/pyoceans/pocean-core/blob/master/pocean/utils.py#L38.