View source for Some Ferret tips and pointers

== Ferret ==
Ferret is a NetCDF vizualisation tool which can be used to postprocess and visualize PCM outputs.

This free software is from NOAA (National Oceanic and Atmospheric Administration) and the relevant webpage where you can learn how to install and use it is here:  https://ferret.pmel.noaa.gov/Ferret/

[For Mac users] It is recommended to use/migrate-to PyFerret.  However, there is a bug in later versions that can render plotting problematic even in the Linux environment.  Fortunately, there is a work around, which we will address specifically for the Mac environment (a post to the Ferret listserv is referenced, and it deals specifically with Linux).  See [[Some_Ferret_tips_and_pointers#Installation_tips| section below]].

== For first timers ==
Ferret is essentially a command line tool so the first thing you'll need to do is launch it from your terminal
<syntaxhighlight lang="bash">
ferret
</syntaxhighlight>
(on some system, e.g. Ubuntu, the executable is called '''ferret_viz''' because another unrelated software also called '''ferret''' exists).

Once under Ferret you should see the Ferret prompt:
<pre>
yes?
</pre>

To load a datafile, for example '''diagfi.nc''' issue command:
<pre>
yes? use diagfi.nc
</pre>
Once the file has been loaded, you can query for its contents with the command '''show data'''
...

== Various tips and pointers ==
...
==== How to make a 1D plot ====
...
==== How to make a 2D map ====
...
==== How to compute a zonal average ====
...

== Installation tips ==

===Mac OSX (PyFerret) and Graphics bug===

====Miniconda====
conda is the preferred environment for the install.  miniconda (a subset of conda) is a lighter-weight option which is a good choice.  Installation instructions for both may be found [[https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html here].

====PyFerret====
Once one has a conda installation of some type, the instructions are straight-forward.  The official installation documentation is [[https://github.com/NOAA-PMEL/PyFerret/blob/master/README.md here].

====Commands used on a Macbook Pro with the M2 ARM chipset (summer 2023)====

* Install miniconda using script

<pre>
bash Miniconda3-latest-MacOSX-arm64.sh      #can "yes" to activate, but we will deactivate

 # do not automatically activate on startup
conda config --set auto_activate_base false    

# initialize for tcsh (it will write code into one's .tcshrc file)
/Users/mwolff/miniconda3/bin/conda init tcsh    
</pre>

* Install pyferret (latest version)
It is recommended that one use virtual environments, and alias the environment activation for simplicity.  The following section is to install pyferret in virtual environment called FERRET.

Note: the pyferret command from the official site did NOT work for me.  It complained about not finding the needed packages.  For reference, this command was 
<pre>
# line below did not work.  it is here for reference
conda create -n FERRET -c conda-forge pyferret ferret_datasets --yes
</pre>

Instead, use the following instead:
<pre>
conda create -n FERRET -c conda-forge/osx-64 pyferret ferret_datasets --yes 
</pre>

This can be actived using an alias for brevity.  In (t)csh world, this would be 
<pre>
alias FERRET "conda activate FERRET"
</pre>

* Dealing with plotting bug.  As can be seen in the post on the Ferret group [https://www.pmel.noaa.gov/maillists/tmap/ferret_users/fu_2019/msg01059.html here], there can be problems for plotting with the latest version(s), even on Linux.  Below, we use a command that works for Mac OSX.

Install a slightly older version of pyferret (i.e., one where the plotting works) using the command in the referenced post in the last paragrph):
<pre>
# we have had to change the channel from the example in the referenced ferret group post (to install for Mac OS
conda create -n oldFERRET -c conda-forge/osx-64/label/cf202003 pyferret ferret_datasets --yes
</pre>

Assuming an alias oldFERRET that activates this older version, a plotting test can be runs as
<pre>
oldFERRET

(oldFERRET) [avory:~] mwolff pyferret
        NOAA/PMEL TMAP
        PyFerret v7.5 (optimized)
        Darwin 17.7.0 - 12/16/19 
        6-Apr-23 10:50
yes? use coads_climatology
yes? fill sst[l=1]

</pre>