Skip navigation
All People > Dan_Patterson > Py... blog > 2018 > March
2018

Help.... Documentation

 

Last thing written... if ever... First thing needed.

I have been messing with formatting my code using numpy doc strings

 

Code documentation.... the view on the left is within the script IDE and the view on the right is what is will look like when viewing a script's help.  Fancy... fancy...

 

 

And! Not only that, your favorite Python Package Manager includes it in their python distribution so Sphinx can use it.

 

 

So here is a little 'dirr' function I wrote since dir(object) returns a messy hard to read output in any form.

Here is the documentation for the function.

def dirr(obj, colwise=True, cols=3, sub=None, prn=True):
    """A formatted dir listing of a module or function.

    Source : arraytools module in tools.py, dirr def

    Return a directory listing of a module's namespace or a part of it if the
    `sub` option is specified.  If  `prn=True`, then it is simply printed. If
    False, then the string is returned.

    Parameters
    ----------
    - colwise : `True` or `1`, otherwise, `False` or `0`
    - cols : pick a size to suit
    - sub : sub='a' all modules beginning with `a`
    - prn : `True` for print or `False` to return output as string

    Notes
    -----

    See the `inspect` module for possible additions like `isfunction`,
    'ismethod`, `ismodule`

    **Examples**::

        dirr(art, colwise=True, cols=3, sub=None, prn=True)  # all columnwise
        dirr(art, colwise=True, cols=3, sub='arr', prn=True) # just the `arr`'s

          (001)    _arr_common     arr2xyz         arr_json
          (002)    arr_pnts        arr_polygon_fc  arr_polyline_fc
          (003)    array2raster    array_fc
          (004)    array_struct    arrays_cols
    """

 

The key (apparently) is indentation, back-ticks and little tricks. 

In Spyder's help documentation, it looks like this. ( More on Spyder as an IDE for your work )

 

 

You can produce whole documentation for your modules or even single 'scripts' to accompany your code.

 

And the function itself makes finding my own documentation easier

Sample output
# ---- by column

dirr(art, colwise=True, cols=4, sub='arr')

----------------------------------------------------------------------
| dir(arraytools) ...
|    <module 'arraytools' from 'C:\\Git_Dan\\arraytools\\__init__.py'>
-------
  (001)    _arr_common     arr_pnts        array2raster    array_struct   
  (002)    arr2xyz         arr_polygon_fc  array_fc        arrays_cols    
  (003)    arr_json        arr_polyline_fc                                

# ---- by row

dirr(art, colwise=False, cols=4, sub='arr')

----------------------------------------------------------------------
| dir(arraytools) ...
|    <module 'arraytools' from 'C:\\Git_Dan\\arraytools\\__init__.py'>
-------
  (001)    _arr_common     arr2xyz         arr_json        arr_pnts       
  (002)    arr_polygon_fc  arr_polyline_fc array2raster                   
  (003)    array_fc        array_struct    arrays_cols                    

# ---- standard method

dir(art)
['__all__', '__args', '__art_modules__', '__art_version__', '__builtins__',
'__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__',
'__spec__', '_arr_common', '_center', '_centroid', '_common', '_convert',
'_cursor_array', '_demo_frmt', '_demo_ma', '_demo_rec', '_densify_2D', '_describe',
'_even_odd', '_extent', '_flat_', '_func', '_geo_array', '_get_shapes', '_help',
'_id_geom_array', '_max', '_min', '_ndarray', '_new_view_', '_pad_', '_pad_even_odd',
'_pad_nan', '_pad_zero', '_props', '_reshape_', '_split_array', '_two_arrays',
'_unpack', '_view_', '_xy', '_xyID', '_xy_idx', 'a_filter', 'a_io', 'all_folders',
'analysis', 'angle_2pnts', 'angle_np', 'angle_seq', 'angles_poly', 'apt', 'arc_np',
'areas', 'arr2xyz', 'arr_json', 'arr_pnts', 'arr_polygon_fc', 'arr_polyline_fc',
'array2raster', 'array_fc', 'array_struct', 'arrays_cols', 'azim_np', 'block',
'block_arr', 'centers', 'centroids', 'change_arr', 'change_fld', 'circle',

.... snip

 

 

Producing links to web links

This may be a bit much, but your documentation can also provide links to http: sites to reference specific web pages from within your documentation.  Here is an example.  The key is to provide a

  • link number ... [1]
  • a name for the link... with trailing __
  • and the actual link itself.

 

 
Web links in script documentation
References:
----------

**creating meshgrids from x,y data and plotting**

[1]
`2D array of values based on coordinates`__:

__ http://stackoverflow.com/questions/30764955/python-numpy-create-2darray-of-values-based-on-coordinates

[2]
`2D histogram issues`__:

__ https://github.com/numpy/numpy/issues/7317


**distance calculations and related** .... (scipy, skikit-learn)

 

The **text** provides bold highlighting.  The [1] on line 6, is the first link with line 7 being the link name in back-tics and trailing __.  Line 9, with the leading __ is the actual link itself.  What is show is a snip of the whole link list shown below.

 

 

Simpler option

You might need a simpler documentation example

    References:
    -----------

    `<https://stackoverflow.com/questions/7352684/how-to-find-the-groups-of-
    sequences-elements-from-an-array-in-numpy>`_.

    `<https://stackoverflow.com/questions/50551776/python-chunk-array-on-
    condition#50551924>`_.

 

This consists of `< at the start and >`_. at the end with the link in between.  This yields...

 

Finally

Remember, documentation is important. If not for yourself, for someone else.

Concave hulls...

 

Tons of examples, some suited to some point clouds, others not so much.

It has greatly amused me over the years that people spend so much time trying to find the 'corner cases' where a particular implementation fails.  For example, the ever popular C - shaped object. 

 

I know... in optical fields, being able to identify the letters of the alphabet or curly snaked-shaped patterns is important.... but, how many times have you sent your field assistant to collect data points with weird shapes.

 

Toolbox links

 

Concave Hulls  this is a separate toolbox

Point Tools or it is contained in this toolbox as well

 

So, regardless of the implementation, they can be illustrative in exploring point patterns and generating containers to describe them.  I recently posted on the Minimum Area Bounding Ellipse (MABE) and I have a toolset that produces Minimum Area Bounding Circles (MABC), rectangles (MABR) and extent rectangles.  This implementation of the concave hull was proposed by Adriano Moreira and Maribel Yasmina Santos in about 2007 and there are several implementations in various languages on GitHub for those needing a trolling session.

 

The 'tightness' of the concave hull by changing the number of nearest neighbors to include when you are trying to decide on which points on the perimeter to keep or dump.   This 'K' factor illustrates some of the possible outcomes.  The thing to watch out for is producing degenerate points which are outside the hull, but are just to much of an outsider to be allowed into the fold.  So in pictoral form,

 

3 neighbours

7 neighbors

11 neighbors

And finally... with the convex hull surrounding it.

And if that isn't tight enough for you, radial sorting and concave hull generation is as tight as it is going to get

 

So if you need to 'contain' something, add the concave hull to your suite of tools.

I will add the implementation of concave and convex hull to my

 

Geometry  Perhaps its due is overlooked. 

A pictoral of some of the things you can do with a set of points with a basic license in ArcMap and PRO with a bit of python and a toolbox to house the scripts in.

 

:---- (1)  -------------------------------------------------------------------------------------------------------------

Begin with some points

Random they are, no order.

:---- (2)  ------------------------------------------------------------------------------------------------------------------

Put order to the set

A radial sort was performed so that the mess was ordered by their angle relative to the x-axis.

Lines were drawn to the center of the cloud (just because)

 

:---- (3)  ------------------------------------------------------------------------------------------------------------------

What do we have now

Since the points are ordered, connect the dots.

:---- (4)  ------------------------------------------------------------------------------------------------------------------

Lets look at things conventionally

Everyone loves a convex hull.  It encompasses the points as a group.  There are other containers.

 

:---- (5)  ------------------------------------------------------------------------------------------------------------------

But some of the points are far from the center

A quick little negative buffer to only keep the points within 90% of the average distance to the center.

 

:---- (6)  ------------------------------------------------------------------------------------------------------------------

Convexity.... A different view on the data

Switching the selection in the above, then connecting the dots gives us a convex-ish hull..

Hmmm I wonder if you can change the rules to get a different view?

 

 

:---- (7)  ------------------------------------------------------------------------------------------------------------------

Every cool map has texture

Fill in boundary, obliterate the dots and 'forest' fill.  Just because we can

 

 

:---- (8)  ------------------------------------------------------------------------------------------------------------------

Connecting each point to its closest

 

:---- (9)  ------------------------------------------------------------------------------------------------------------------

Connections to 3 closest

Starting to see groupings and spaces.

 

:---- (10)  ------------------------------------------------------------------------------------------------------------------

Trees are useful (MST)

 

:---- (11)  ------------------------------------------------------------------------------------------------------------------

Make patterns from a single point (Ulam spiral)

:---- (12)  ------------------------------------------------------------------------------------------------------------------

Archimedes only needed a single point

 

:---- (13)  ------------------------------------------------------------------------------------------------------------------

 

:---- (14)  ------------------------------------------------------------------------------------------------------------------