visidata 3.0.2__py3-none-any.whl → 3.1__py3-none-any.whl

visidata/graph.py

@@ -1,10 +1,16 @@
 import math
 
-from visidata import VisiData, Canvas, Sheet, Progress, BoundingBox, Point
-from visidata import vd, asyncthread, dispwidth, colors, clipstr
+from visidata import VisiData, Canvas, Sheet, Progress, BoundingBox, Point, ColumnsSheet
+from visidata import vd, asyncthread, dispwidth, colors, clipstr, ColorAttr, update_attr
+from visidata.type_date import date
+from statistics import median
 
 vd.theme_option('color_graph_axis', 'bold', 'color for graph axis labels')
 vd.theme_option('disp_graph_tick_x', '╵', 'character for graph x-axis ticks')
+vd.theme_option('color_graph_refline', '', 'color for graph reference value lines')
+vd.theme_option('disp_graph_reflines_x_charset', '▏││▕', 'charset to render vertical reference lines on graph')
+vd.theme_option('disp_graph_reflines_y_charset', '▔──▁', 'charset to render horizontal reference lines on graph')
+vd.theme_option('disp_graph_multiple_reflines_char', '▒', 'char to render multiple parallel reflines')
 
 
 @VisiData.api
@@ -21,7 +27,7 @@ class InvertedCanvas(Canvas):
         'adjust visibleBox.xymin so that canvasPoint is plotted at plotterPoint'
         self.visibleBox.xmin = canvasPoint.x - self.canvasW(plotterPoint.x-self.plotviewBox.xmin)
         self.visibleBox.ymin = canvasPoint.y - self.canvasH(self.plotviewBox.ymax-plotterPoint.y)
-        self.refresh()
+        self.resetBounds()
 
     def rowsWithin(self, plotter_bbox):
         return super().rowsWithin(plotter_bbox, invert_y=True)
@@ -29,9 +35,10 @@ class InvertedCanvas(Canvas):
     def zoomTo(self, bbox):
         super().zoomTo(bbox)
         self.fixPoint(Point(self.plotviewBox.xmin, self.plotviewBox.ymin),
-                      Point(bbox.xmin, bbox.ymax + 1/4*self.canvasCharHeight))
+                      Point(bbox.xmin, bbox.ymax))
+        self.resetBounds()
 
-    def scaleY(self, canvasY):
+    def scaleY(self, canvasY) -> int:
         'returns a plotter y coordinate for a canvas y coordinate, with the y direction inverted'
         return self.plotviewBox.ymax-round((canvasY-self.visibleBox.ymin)*self.yScaler)
 
@@ -69,6 +76,11 @@ class GraphSheet(InvertedCanvas):
         self.ylabel_maxw = 0
         super().__init__(*names, **kwargs)
 
+        self.reflines_x = []
+        self.reflines_y = []
+        self.reflines_char_x = {}    # { x value in character coordinates -> character to use to draw that vertical line }
+        self.reflines_char_y = {}    # { y value in character coordinates -> character to use to draw that horizontal line }
+
         vd.numericCols(self.xcols) or vd.fail('at least one numeric key col necessary for x-axis')
         self.ycols or vd.fail('%s is non-numeric' % '/'.join(yc.name for yc in kwargs.get('ycols')))
 
@@ -111,11 +123,45 @@ class GraphSheet(InvertedCanvas):
 
         self.xzoomlevel=self.yzoomlevel=1.0
         self.resetBounds()
-        self.refresh()
 
-    def resetBounds(self):
-        super().resetBounds()
+    def draw(self, scr):
+        windowHeight, windowWidth = scr.getmaxyx()
+        if self.needsRefresh:
+            self.render(windowHeight, windowWidth)
+
+        # required because we use clear_empty_squares=False for draw_pixels()
+        self.draw_empty(scr)
+        # draw reflines first so pixels draw over them
+        self.draw_reflines(scr)
+        # use clear_empty_squares to keep reflines
+        self.draw_pixels(scr, clear_empty_squares=False)
+        self.draw_labels(scr)
+
+    def draw_reflines(self, scr):
+        cursorBBox = self.plotterCursorBox
+        # draws only on character cells that have reflines, leaves other cells unaffected
+        for char_y in range(0, self.plotheight//4):
+            has_y_line = char_y in self.reflines_char_y.keys()
+            for char_x in range(0, self.plotwidth//2):
+                has_x_line = char_x in self.reflines_char_x.keys()
+                if has_x_line or has_y_line:
+                    cattr = colors.color_refline
+                    if has_x_line:
+                        ch = self.reflines_char_x[char_x]
+                        # where two lines cross, draw the vertical line, not the horizontal one
+                    elif has_y_line:
+                        ch = self.reflines_char_y[char_y]
+                    # draw cursor
+                    if cursorBBox.contains(char_x*2, char_y*4) or \
+                        cursorBBox.contains(char_x*2+1, char_y*4+3):
+                        cattr = update_attr(cattr, colors.color_current_row)
+                    scr.addstr(char_y, char_x, ch, cattr.attr)
+
+    def resetBounds(self, refresh=True):
+        super().resetBounds(refresh=False)
         self.createLabels()
+        if refresh:
+            self.refresh()
 
     def moveToRow(self, rowstr):
         ymin, ymax = map(float, map(self.parseY, rowstr.split()))
@@ -123,6 +169,43 @@ class GraphSheet(InvertedCanvas):
         self.cursorBox.h = ymax-ymin
         return True
 
+    def plot_elements(self, invert_y=True):
+        self.plot_reflines()
+        super().plot_elements(invert_y=True)
+
+    def plot_reflines(self):
+        self.reflines_char_x = {}
+        self.reflines_char_y = {}
+
+        bb = self.visibleBox
+        xmin, ymin, xmax, ymax = bb.xmin, bb.ymin, bb.xmax, bb.ymax
+
+        for data_y in self.reflines_y:
+            data_y = float(data_y)
+            if data_y >= ymin and data_y <= ymax:
+                char_y, offset = divmod(self.scaleY(data_y), 4)
+                chars = self.options.disp_graph_reflines_y_charset
+                # if we're drawing two different reflines in the same square, fill it with a different char
+                if char_y in self.reflines_char_y and self.reflines_char_y[char_y] != chars[offset]:
+                    self.reflines_char_y[char_y] = vd.options.disp_graph_multiple_reflines_char
+                else:
+                    self.reflines_char_y[char_y] = chars[offset]
+
+        for data_x in self.reflines_x:
+            data_x = float(data_x)
+            if data_x >= xmin and data_x <= xmax:
+                plot_x = self.scaleX(data_x)
+                # plot_x is an integer count of plotter pixels, and each character box has 2 plotter pixels
+                char_x = plot_x // 2
+                # To subdivide the 2 plotter pixels per square into 4 zones, we have to first multiply by 2.
+                offset = 2*plot_x % 4
+                chars = self.options.disp_graph_reflines_x_charset
+                # if we're drawing two different reflines in the same square, fill it with a different char
+                if char_x in self.reflines_char_x and self.reflines_char_x[char_x] != chars[offset]:
+                    self.reflines_char_y[char_x] = vd.options.disp_graph_multiple_reflines_char
+                else:
+                    self.reflines_char_x[char_x] = chars[offset]
+
     def moveToCol(self, colstr):
         xmin, xmax = map(float, map(self.parseX, colstr.split()))
         self.cursorBox.xmin = xmin
@@ -163,20 +246,23 @@ class GraphSheet(InvertedCanvas):
         return self.ycols[0].type(txt)
 
     def add_y_axis_label(self, frac):
-        txt = self.formatYLabel(self.visibleBox.ymin + frac*self.visibleBox.h)
+        label_data_y = self.visibleBox.ymin + frac*self.visibleBox.h
+        txt = self.formatYLabel(label_data_y)
         w = (dispwidth(txt)+1)*2
         if self.ylabel_maxw < w:
             self.ylabel_maxw = w
+        y = self.scaleY(label_data_y)
 
         # plot y-axis labels on the far left of the canvas, but within the plotview height-wise
-        self.plotlabel(0, self.plotviewBox.ymin + (1.0-frac)*self.plotviewBox.h, txt, 'graph_axis')
+        self.plotlabel(0, y, txt, 'graph_axis')
 
     def add_x_axis_label(self, frac):
-        txt = self.formatXLabel(self.visibleBox.xmin + frac*self.visibleBox.w)
+        label_data_x = self.visibleBox.xmin + frac*self.visibleBox.w
+        txt = self.formatXLabel(label_data_x)
         tick = vd.options.disp_graph_tick_x or ''
 
         # plot x-axis labels below the plotviewBox.ymax, but within the plotview width-wise
-        x = self.plotviewBox.xmin + frac*self.plotviewBox.w
+        x = self.scaleX(label_data_x)
 
         if frac < 1.0:
             txt = tick + txt
@@ -223,9 +309,62 @@ class GraphSheet(InvertedCanvas):
         rows = super().rowsWithin(plotter_bbox)
         return sorted(rows, key=lambda r: self.row_order[self.source.rowid(r)])
 
+    def draw_refline_x(self):
+        xcol = vd.numericCols(self.xcols)[0]
+        xtype = xcol.type
+        val = median(xcol.getValues(self.sourceRows))
+        suggested = format_input_value(val, xtype)
+        xstrs = vd.input("add line(s) at x = ", type="reflinex", value=suggested, defaultLast=True).split()
+
+        for xstr in xstrs:
+            vals = [ v.strip() for v in xstr.split(',') ]
+            if len(vals) != len(self.xcols):
+                vd.fail(f'must have {len(self.xcols)} x values, had {len(vals)} values: {xstr}')
+            self.reflines_x += [xtype(val) for xcol, val in zip(self.xcols, vals) if xtype(val) not in self.reflines_x ]
+        self.refresh()
+
+    def draw_refline_y(self):
+        ytype = self.ycols[0].type
+        val = median(self.ycols[0].getValues(self.sourceRows))
+        suggested = format_input_value(val, ytype)
+        ystrs = vd.input("add line(s) at y = ", type="refliney", value=suggested, defaultLast=True).split()
+
+        self.reflines_y += [ ytype(y) for y in ystrs if ytype(y) not in self.reflines_y ]
+        self.refresh()
+
+    def erase_refline_x(self):
+        if len(self.reflines_x) == 0:
+            vd.fail(f'no x refline to erase')
+        xtype = vd.numericCols(self.xcols)[0].type
+        suggested = format_input_value(self.reflines_x[0], xtype)
+
+        xstrs = vd.input('remove line(s) at x = ', value=suggested, type='reflinex', defaultLast=True).split()
+        for input_x in xstrs:
+            self.reflines_x.remove(xtype(input_x))
+        self.refresh()
+
+    def erase_refline_y(self):
+        ytype = self.ycols[0].type
+        suggested = format_input_value(self.reflines_y[0], ytype) if self.reflines_y else ''
+        ystrs = vd.input('remove line(s) at y = ', value=suggested, type='refliney', defaultLast=True).split()
+        for y in ystrs:
+            try:
+                self.reflines_y.remove(ytype(y))
+            except ValueError:
+                vd.fail(f'value {y} not in reflines_y')
+        self.refresh()
+
+def format_input_value(val, type):
+    '''format a value for entry into vd.input(), so its representation has no spaces and no commas'''
+    if type is date:
+        return val.strftime('%Y-%m-%d')
+    else:
+        return str(val)
+
 
 Sheet.addCommand('.', 'plot-column', 'vd.push(GraphSheet(sheet.name, "graph", source=sheet, sourceRows=rows, xcols=keyCols, ycols=numericCols([cursorCol])))', 'plot current numeric column vs key columns; numeric key column is used for x-axis, while categorical key columns determine color')
 Sheet.addCommand('g.', 'plot-numerics', 'vd.push(GraphSheet(sheet.name, "graph", source=sheet, sourceRows=rows, xcols=keyCols, ycols=numericCols(nonKeyVisibleCols)))', 'plot a graph of all visible numeric columns vs key columns')
+ColumnsSheet.addCommand('g.', 'plot-source-selected', 'vd.push(GraphSheet(sheet.source[0].name, "graph", source=source[0], sourceRows=source[0].rows, xcols=source[0].keyCols, ycols=numericCols(selectedRows)))', 'plot a graph of all selected columns vs key columns on source sheet')
 
 # swap directions of up/down
 InvertedCanvas.addCommand(None, 'go-up', 'if cursorBox: sheet.cursorBox.ymin += cursorBox.h', 'move cursor up by its height')
@@ -257,6 +396,12 @@ def set_x(sheet, s):
 Canvas.addCommand('y', 'resize-y-input', 'sheet.set_y(input("set ymin ymax="))', 'set ymin/ymax on graph axes')
 Canvas.addCommand('x', 'resize-x-input', 'sheet.set_x(input("set xmin xmax="))', 'set xmin/xmax on graph axes')
 
+GraphSheet.addCommand('gx', 'draw-refline-x', 'sheet.draw_refline_x()', 'draw a vertical line at x-values (space-separated)')
+GraphSheet.addCommand('gy', 'draw-refline-y', 'sheet.draw_refline_y()', 'draw a horizontal line at y-values (space-separated)')
+GraphSheet.addCommand('zx', 'erase-refline-x', 'sheet.erase_refline_x()', 'remove a horizontal line at x-values (space-separated)')
+GraphSheet.addCommand('zy', 'erase-refline-y', 'sheet.erase_refline_y()', 'remove a vertical line at y-values (space-separated)')
+GraphSheet.addCommand('gzx', 'erase-reflines-x', 'sheet.reflines_x = []; sheet.refresh()', 'erase all vertical x-value lines')
+GraphSheet.addCommand('gzy', 'erase-reflines-y', 'sheet.reflines_y = []; sheet.refresh()', 'erase any horizontal y-value lines')
 
 vd.addGlobals({
     'GraphSheet': GraphSheet,
@@ -266,4 +411,10 @@ vd.addGlobals({
 vd.addMenuItems('''
     Plot > Graph > current column > plot-column
     Plot > Graph > all numeric columns > plot-numerics
+    Plot > Refline > draw at x coord (vert) > draw-refline-x
+    Plot > Refline > draw at y coord (horiz) > draw-refline-y
+    Plot > Refline > erase at x coord (vert) > erase-refline-x
+    Plot > Refline > erase at y coord (horiz) > erase-refline-y
+    Plot > Refline > erase all x (vert) > erase-reflines-x
+    Plot > Refline > erase all y (horiz) > erase-reflines-y
 ''')

visidata/guide.py

@@ -8,7 +8,8 @@ Each guide shows you how to use a particular feature in VisiData. Gray guides ha
 import re
 
 from visidata import vd, BaseSheet, Sheet, ItemColumn, Column, VisiData, ENTER, RowColorizer, AttrDict, MissingAttrFormatter
-from visidata import wraptext
+from visidata import wraptext, Path, CellColorizer
+import visidata
 
 guides_list = '''
 GuideIndex ("A Guide to VisiData Guides (you are here)")
@@ -20,7 +21,7 @@ CommandsSheet ("How to find the command you want run")
 MovementGuide ("Movement and search")
 InputGuide ("Input keystrokes")
 SortGuide ("Sorting")
-ColumnsGuide ("Rename, hide, and resize columns")
+ColumnsGuide ("Resize, hide, and rename columns")
 TypesSheet ("Column types")
 CommandLog  ("Undo and Replay")
 
@@ -46,7 +47,7 @@ AggregatorsSheet ("Aggregations like sum, mean, and distinct")
 FrequencyTable ("Frequency Tables are how you GROUP BY")
 PivotGuide ("Pivot Tables are just Frequency Tables with more columns")
 MeltGuide ("Melt is just Unpivot")
-JsonGuide ("Some special features for JSON") # with expand/contract, unfurl
+JsonSheet ("Some special features for JSON") # with expand/contract, unfurl
 RegexGuide ("Matching and Transforming Strings with Regex")
 GraphSheet ("Basic scatterplots and other graphs")
 WindowFunctionGuide ("Perform operations on groups of rows")
@@ -62,10 +63,15 @@ ColorSheet ("See available colors")
 MacrosSheet ("Recording macros")
 MemorySheet ("Making note of certain values")
 
+# Specific use cases
+
+XsvGuide ("CSV/TSV and other text-delimited formats")
+GrepSheet ("Load output of grep-like tools")
+
 # advanced usage and developers
 
 ThreadsSheet ("Threads past and present")
-PyobjSheet ("Inspecting internal Python objects")
+DeveloperGuide ("Inspecting internal Python objects")
 
 #  appendices
 
@@ -75,8 +81,10 @@ InputEditorGuide ("Using the builtin line editor")
 vd.guides = {}  # name -> guidecls
 
 @VisiData.api
-def addGuide(vd, name, guidecls):
-    vd.guides[name] = guidecls
+def addGuide(vd, name):
+    guideSource = Path(vd.pkg_resources_files(visidata)/f'guides/{name}.md')
+    if guideSource.exists():
+        vd.guides[name] = GuideSheet(name, source=guideSource)
 
 @VisiData.api
 class GuideIndex(Sheet):
@@ -84,7 +92,7 @@ class GuideIndex(Sheet):
 
     rowtype = 'guides' # rowdef: list(guide number, guide name, topic description, points, max_points)
     columns = [
-        ItemColumn('n', 0, type=int),
+        ItemColumn('n', 0, width=0, type=int),
         ItemColumn('name', 1, width=0),
         ItemColumn('topic', 2, width=60),
     ]
@@ -96,7 +104,9 @@ class GuideIndex(Sheet):
         for line in guides_list.splitlines():
             m = re.search(r'(\w+?) \("(.*)"\)', line)
             if m:
-                yield [i] + list(m.groups())
+                guidename, description = list(m.groups())
+                vd.addGuide(guidename)
+                yield [i, guidename, description]
                 i += 1
 
     def openRow(self, row):
@@ -104,25 +114,25 @@ class GuideIndex(Sheet):
         return vd.getGuide(name)
 
 class OptionHelpGetter:
-    'For easy and consistent formatting in sidebars and helpstrings, use {vd.options.help.opt_name}.'
+    'For easy and consistent formatting in sidebars and helpstrings, use {help.options.opt_name}.'
     def __getattr__(self, optname):
         opt = vd.options._get(optname, 'default')
-        return f'[:onclick options-sheet {optname}][:longname]{optname}[/][/]: to {opt.helpstr} (default: {opt.value})'
+        return f'[:onclick options-sheet {optname}][:longname_guide]{optname}[/][/]: {opt.helpstr} (default: {opt.value})'
 
 
 class CommandHelpGetter:
-    'For easy and consistent formatting in sidebars and helpstrings, use {vd.commands.help.long_name}.'
+    'For easy and consistent formatting in sidebars and helpstrings, use {help.commands.long_name}.'
     def __init__(self, cls):
         self.cls = cls
         self.helpsheet = vd.HelpSheet()
-        self.helpsheet.ensureLoaded()
+        vd.sync(self.helpsheet.ensureLoaded())
 
     def __getattr__(self, k):
         return self.__getitem__(k)
 
     def __getitem__(self, k):
         longname = k.replace('_', '-')
-        binding = self.helpsheet.revbinds.get(longname, [None])[0]
+        binding = self.helpsheet.revbinds.get(longname, [None])[0] or '<unbound>'
         # cmddict has a SheetClass associated with each command
         # go through all the parents of the Sheet type, to look for the command
         for cls in self.cls.superclasses():
@@ -137,11 +147,11 @@ class CommandHelpGetter:
             if not m:
                 m = re.search(r'input(\w*)\("', cmd.execstr, re.IGNORECASE)
             if m:
-                inputtype = m.groups()[0].lower()
-                binding += f'[:45] {inputtype}[/]'
+                inputtype = m.groups()[0].lower() or 'input'
+                binding += f' <{inputtype}>'
 
         helpstr = cmd.helpstr
-        return f'[:keys]{binding}[/] ([:longname]{longname}[/]) to {helpstr}'
+        return f'[:code]{binding}[/] ([:longname_guide]{longname}[/]) to {helpstr}'
 
 
 class GuideSheet(Sheet):
@@ -152,14 +162,31 @@ class GuideSheet(Sheet):
             ItemColumn('guide', 1, width=80, displayer='full'),
             ]
     precious = False
-    guide_text = ''
-    sheettype = Sheet
+    colorizers = [CellColorizer(4, 'color_sidebar', lambda s,c,r,v: True)]
 
     def iterload(self):
+        self.metadata = AttrDict(sheettype='Sheet')
+        text = self.source.open(mode='r').read()
         winWidth = 78
-        helper = AttrDict(commands=CommandHelpGetter(self.sheettype),
+
+        # parsing front matter
+        sections = text.split('---\n', maxsplit=2)
+        for section in sections[:-1]:
+            for config in section.splitlines():
+                config = config.strip()
+                if config:
+                    try:
+                        key, val = config.split(': ', maxsplit=1)
+                    except ValueError:
+                        vd.fail('incorrect front matter syntax')
+                    self.metadata[key] = val
+
+        # formatting text
+        helper = AttrDict(commands=CommandHelpGetter(vd.getGlobals()[self.metadata.sheettype]),
                           options=OptionHelpGetter())
-        guidetext = MissingAttrFormatter().format(self.guide_text, help=helper, vd=vd)
+        guidetext = MissingAttrFormatter().format(sections[-1], help=helper, vd=vd)
+
+        # parsing guide
         for startingLine, text in enumerate(guidetext.splitlines()):
             text = text.strip()
             if text:
@@ -169,11 +196,10 @@ class GuideSheet(Sheet):
                 yield [startingLine+1, text]
 
 
-
 @VisiData.api
 def getGuide(vd, name): # -> GuideSheet()
     if name in vd.guides:
-        return vd.guides[name]()
+        return vd.guides[name]
     vd.warning(f'no guide named {name}')
 
 BaseSheet.addCommand('', 'open-guide-index', 'vd.push(GuideIndex("VisiData_Guide"))', 'open VisiData guides table of contents')
@@ -189,8 +215,15 @@ def inputKeys(vd, prompt):
 
 @BaseSheet.api
 def getCommandInfo(sheet, keys):
+    if not keys:
+        return ''
     cmd = sheet.getCommand(keys)
-    return CommandHelpGetter(type(sheet))[cmd.longname]
+    if cmd:
+        return CommandHelpGetter(type(sheet))[cmd.longname]
+    else:
+        vd.warning(f'no command bound to {keys} on {sheet}')
+
+GuideSheet.options.color_current_row = "underline"
 
 vd.addCommand('', 'show-command-info', 'status(getCommandInfo(inputKeys("get command for keystrokes: ")))', 'show longname and helpstring for keybinding')
 
@@ -200,4 +233,4 @@ vd.addMenuItems('''
 
 vd.optalias('guides', 'preplay', 'open-guide-index')
 
-vd.addGlobals({'GuideSheet':GuideSheet, "CommandHelpGetter": CommandHelpGetter, "OptionHelpGetter": OptionHelpGetter})
+vd.addGlobals({"CommandHelpGetter": CommandHelpGetter, "OptionHelpGetter": OptionHelpGetter})

visidata/guides/ClipboardGuide.md

@@ -0,0 +1,48 @@
+# Copy, Cut and Paste...
+
+## ...rows to/from the internal clipboard
+
+- {help.commands.copy_row}
+- {help.commands.copy_selected}
+
+- {help.commands.cut_row}
+- {help.commands.cut_selected}
+
+- {help.commands.paste_after}
+- {help.commands.paste_before}
+
+## ...cells to/from the internal clipboard
+
+- {help.commands.copy_cell}
+- {help.commands.cut_cell}
+- {help.commands.paste_cell}
+
+## ...columns from the intenral clipboard
+
+- {help.commands.copy_cells}
+- {help.commands.cut_cells}
+- {help.commands.setcol_clipboard}
+
+If there are fewer values in the clipboard than in the selected target column, the clipboard values will be repeated in sequence.
+
+## ....to/from the system clipboard
+
+- {help.commands.syscopy_cell}
+- {help.commands.syscopy_cells}
+
+- {help.commands.syscopy_row}
+- {help.commands.syscopy_selected}
+
+- {help.commands.syspaste_cells}
+- {help.commands.syspaste_cells_selected}
+
+## Paste a new sheet from the system clipboard
+
+- {help.commands.open_syspaste}
+
+The paste command will prompt for the filetype, so the input data (from the clipboard) can be in any supported format.
+
+## Relevant options
+
+- {help.options.clipboard_copy_cmd}
+- {help.options.clipboard_paste_cmd}

visidata/guides/ColumnsGuide.md

@@ -0,0 +1,52 @@
+# Resize, hide, and rename columns
+
+## Resize the current column
+
+- {help.commands.resize_col_max}
+- {help.commands.resize_col_input}
+- {help.commands.resize_col_half}
+
+## Resize multiple columns
+
+- {help.commands.resize_cols_input}
+
+## Hide and Unhide columns
+
+Clean up the sheet by hiding unwanted columns.  Hidden columns are still present, but not visible in the main set of columns.
+(They are minimized on the right side and can be unhidden with {help.commands.resize_col_max}.
+
+- {help.commands.hide_col}
+- {help.commands.unhide_cols}
+
+Use {help.commands.columns_sheet} to control visibility as well.
+
+## Rename columns
+
+- {help.commands.rename_col}
+
+## Rename one or more columns using data 
+
+Rename one or more columns using data from the sheet:
+
+- {help.commands.rename_col_selected}
+- {help.commands.rename_cols_row}
+- {help.commands.rename_cols_selected}
+
+## Clean column names
+
+Rename columns to be valid Python identifiers that can be used in column
+expressions.
+
+- {help.commands.normalize_col_names}
+- {help.commands.clean_names}
+
+## Change row height
+
+Sometimes the data for a cell will not fit within the current width. If the
+data is large, or spans multiple lines, change the row height to show more for
+the current column width. Row height adjustments can also be combined with
+column width changes.
+
+- {help.commands.toggle_multiline}
+- {help.commands.resize_height_input}
+- {help.commands.resize_height_max}

visidata/guides/CommandsSheet.md

@@ -0,0 +1,28 @@
+# How to find commands
+
+## Command Palette
+
+- {help.commands.exec_longname}
+
+Start typing a command longname or keyword in its helpstring.
+
+- [:code]Enter[/] to execute top command.
+- [:code]Tab[/] to highlight top command and provide a numeric jumplist.
+
+When a command is highlighted:
+
+- [:code]Tab[/]/[:code]Shift+Tab[/] to cycle highlighted command.
+- [:code]Enter[/] to execute highlighted command.
+- [:code]0-9[/] to execute numbered command.
+
+## Command Sheet
+
+The Command Sheet lists all of the available commands, their keyboard bindings, function names, and other information.
+
+- {help.commands.help_commands_all}
+- {help.commands.help_commands}
+
+'description' and 'longname' column: useful to find rows that share a longname suffix or prefix. E.g, `save` or `selected`.
+
+'keystrokes' and 'all_bindings' column: useful to search for keybindings. E.g, `Ctrl` or `F`.
+

visidata/guides/DirSheet.md

@@ -0,0 +1,34 @@
+---
+sheettype: DirSheet
+---
+# Directory Sheet
+
+The **DirSheet** is a display of files and folders in the *source* directory.
+
+To load a **DirSheet**:
+
+- provide a directory as a source on the CLI (e.g. [:code]vd sample_data/[/])
+- {help.commands.open_dir_current} (equivalent to [:code]vd .[/])
+
+Use the **DirSheet** to find and open files:
+
+- {help.commands.open_row_file}
+- {help.commands.open_rows}
+- {help.commands.open_dir_parent}
+- {help.commands.sysopen_row}
+
+Use the **DirSheet** as a file manager:
+
+- {help.commands.copy_row}
+- {help.commands.copy_selected}
+- [:keys]d[/] ([:longname]delete-row[/]) to delete file from filesystem
+- [:keys]e[/] ([:longname]edit-cell[/]) to change file metadata (all of the file metadata, except for *filetype*, is modifiable)
+
+Modifications on the **DirSheet** are deferred - they do not take effect on the filesystem itself until they are confirmed.
+- {help.commands.commit_sheet}
+
+## Options of Interest (must reload to take effect)
+
+- pass the flag [:code]-r[/] ([:code]--recursive[/]) on the CLI to display all of the files in all subfolders
+- {help.options.dir_depth}
+- {help.options.dir_hidden}

visidata/guides/ErrorsSheet.md

@@ -0,0 +1,17 @@
+# What was that error?
+
+Status messages include [:warning]warnings[/] and [:error]errors[/].
+
+A command may issue a [:warning]warning[/] status and continue running.
+A command that [:warning]fails[/] or [:error]errors[/] is aborted.
+
+## Investigating errors further
+
+If a Python Exception like [:error]RuntimeError[/] appears in the sidebar:
+
+- {help.commands.error_recent}
+- {help.commands.errors_all}
+
+If [:note_type]{vd.options.disp_note_fmtexc}[/] or [:error]{vd.options.disp_note_getexc}[/] appear inside a cell, it indicates an error happened during calculation, type-conversion, or formatting.  When the cursor is on an error cell:
+
+- {help.commands.error_cell}

visidata/guides/FrequencyTable.md

@@ -0,0 +1,42 @@
+# Frequency Tables are how you GROUP BY
+
+Frequency Tables group rows into bins by column value, and includes summary columns for source columns with aggregators.
+
+Set `--numeric-binning` to bin numeric rows into ranges instead of discrete values.
+
+- {help.commands.freq_col}
+
+- {help.commands.freq_keys}
+
+- {help.commands.freq_summary} 
+
+## Aggregators
+
+A **Frequency Table** contains a summary columns for each aggregator added to a source column.
+These aggregators need to be added before creating the Frequency Table.
+Examples of aggregators include min, max, sum, distinct, count, and list.
+
+- {help.commands.aggregate-col}
+
+Note: set an appropriate type for the aggregator target column, for example {help.commands.type_float}.
+
+## Explore the data
+
+Dive into a group to see the underlying row(s) using the **Frequency Table**:
+
+- {help.commands.open_row}
+- {help.commands.dive_selected}
+
+Select a group to select all of its underlying rows in the source sheet.
+
+## Using Split Panes with Frequency Tables
+
+Press `Shift+Z` to open a split pane, and then `Shift+F` to create a **Frequency Table**. The **Frequency Table** will automatically open in the other pane.
+
+See the `SplitpanesGuide` for more.
+
+#### Options
+
+- {help.options.disp_histogram}
+- {help.options.histogram_bins}
+- {help.options.numeric_binning}