Package: xcsv-plot-map
xcsv-plot-mapxcsv-plot-map is a subpackage ofxcsv.  It's main purpose is to provide a simple CLI for plotting extended CSV (XCSV) files, and locating the data on a map, given an extended header section with geographical coordinates.  These will typically detail where the data were acquired.  It inherits from thexcsv-plotsubpackage of xcsv.InstallThe package can be installed from PyPI:$pipinstallxcsv-plot-mapNotes on installing Cartopyxcsv-plot-map has a dependency on Cartopy.  In turn, Cartopy requires the Proj library.  If you find that you can't install Cartopy because the version of the Proj library on your system is too old, then you can build a local version of the Proj library.  This should be a fairly straightforward build.  You may then find that the Cartopy package installs OK, but that you get the following segfault at runtime when trying to use xcsv-plot-map:free():invalidsize
Aborted(coredumped)This is a known issue.  A suggested fix for this is to reinstall the Pythonshapelypackage.  First remove it:$pipuninstallshapelyand then reinstall it with specificpipoptions:$pipinstall--no-binary:all:shapelyThis may take a while, but should resolve the segfault issue and everything should work.Using the packageAn XCSV file with anACDD-compliantextended header section, including geographical coordinates inlongitudeandlatitudeheader items, and well-annotated column-headers, already provides much of the text needed to make an informative plot and map, so we can just plot the XCSV file directly from the command line.  This is the purpose of thexcsv-plot-mapsubpackage.  For example:$python3-mxcsv.plot_map-x0-y1example.csvNote here that we're callingxcsv-plot-mapas amodule main.  As a convenience, this invocation is wrapped as a console script when installing the package, hence the following invocation is equivalent:$xcsv_plot_map-x0-y1example.csvIn addition to using the CLI, the package can be used as a Python library.  The main class isPlot.  This is inherited from thexcsv-plot.Plotclass, with some overridden methods.  The class provides methods to plot a given list of datasets (XCSV objects), and locate them on a map:importxcsvimportxcsv.plot_mapasxpmfilenames=['example1.csv','example2.csv','example3.csv']datasets=[]forfilenameinfilenames:withxcsv.File(filename)asf:datasets.append(f.read())plotter=xpm.Plot()plotter.plot_datasets(datasets,xidx=0,yidx=1)Command line usageCalling the script with the--helpoption will show the following usage:$python-mxcsv.plot_map--help
usage:xcsv_plot_map[-h][-xXIDX|-XXCOL][-yYIDX|-YYCOL][--x-labelXLABEL][--y-labelYLABEL][--invert-x-axis][--invert-y-axis][--titleTITLE][--captionCAPTION][--label-keyLABEL_KEY][-sFIGSIZEFIGSIZE][-pPROJECTION][-m][-bBG_IMG_PATH][-oOUT_FILE][-PPLOT_OPTS][-S][-V]in_file[in_file...]plotthegivenXCSVfilesandlocatethedataonamap

positionalarguments:in_fileinputXCSVfile(s)optionalarguments:-h,--helpshowthishelpmessageandexit-xXIDX,--x-idxXIDXcolumnindex(zero-based)containingvaluesforthex-axis-XXCOL,--x-columnXCOLcolumnlabelcontainingvaluesforthex-axis-yYIDX,--y-idxYIDXcolumnindex(zero-based)containingvaluesforthey-axis-YYCOL,--y-columnYCOLcolumnlabelcontainingvaluesforthey-axis--x-labelXLABELtexttobeusedfortheplotx-axislabel--y-labelYLABELtexttobeusedfortheploty-axislabel--invert-x-axisinvertthex-axis--invert-y-axisinvertthey-axis--titleTITLEtexttobeusedfortheplottitle--captionCAPTIONtexttobeusedfortheplotcaption--label-keyLABEL_KEYkeyoftheheaderitemintheextendedheadersectionwhosevaluewillbeusedfortheplotlegendlabel-sFIGSIZEFIGSIZE,--figsizeFIGSIZEFIGSIZEsizeofthefigure(widthheight)-pPROJECTION,--map-projectionPROJECTIONprojectiontousefordisplayingthesitecoordinatesonthemap(oneoftheCRSclassesprovidedbyCartopy)-m,--plot-on-mapinsteadofaplotalongsideasitemap,showjustamapandplotthecoordinatedatadirectlyonthemap-bBG_IMG_PATH,--background-imageBG_IMG_PATHpathtoanimagetoshowinthebackgroundoftheplot-oOUT_FILE,--out-fileOUT_FILEoutputplotfile-PPLOT_OPTS,--plot-optionsPLOT_OPTSoptionsfortheplot,specifiedasasimpleJSONobject-S,--scatter-plotsetplotoptions(see-P)toproduceascatterplot-V,--versionshowprogram'sversionnumberandexitExamples

GivenanXCSVfilewithanACDD-compliantextendedheadersection,includinggeographicalcoordinatesinlongitudeandlatitude,andasinglecolumn(atcolumn0)ofdatavalues:# id: 1# title: The title# latitude: -73.86 (degree_north)# longitude: -65.46 (degree_east)depth(m)0.5751.1252.225

Thenthefollowinginvocationwillplottheonlycolumnonthey-axis,withthex-axistheindicesofthedatapoints,andwilllocatethecoordinatesonamap:

python3-mxcsv.plot_mapinput.csv

Ifthefilealsocontainsasuitablevariableforthex-axis:# id: 1# title: The title# latitude: -73.86 (degree_north)# longitude: -65.46 (degree_east)time(year)[a],depth(m)2012,0.5752011,1.1252010,2.225thenthecolumnstobeusedforthex-andy-axescanbespecifiedthus:

python3-mxcsv.plot_map-x0-y1input.csv