2.0.0 - PEP8, FutureWarnings

2.0.0 Future Warnings and Deprecations are Here!

To adhere to the Pep 8 - Python Style centerline-width has undergone a large overhaul to user functions and class names. 2.0.0 will be the first version release to include deprecation warnings for older function/variable/class names. These functions will continue to work with their original names, but will start to throw FutureWarning and eventually functionality from these original names will be dropped (but will include helpful tips to transition)

The PEP8 update includes changes to:

• Group imports in alphabetical ordered groups (standard library imports, related third party imports, local specific imports
• Class names use CamelCase convention
• Function names are lowercase and snakecase
• Back end function names preceded by underscore

Why?

These changes is being done to best maintain centerline-width for future work and collaboration. centerline-width was originally intended to function for personal academic work, but has been expanded to better serve the geoscience community. Many original decisions were made to maximize clarity, but ended up with verbose, non-ideal, and difficult to read naming conventions (i.e. centerlineEqualDistanceRelative). As centerline-width has been moving to a more complete stage, this seemed like a good time to clean up lingering tech debt before moving onto the next stage of river analysis development.

If you have any questions, feel free to submit it at the centerline-width/issues

Impacted Deprecations:

Functions and Variable Names:
extractPointsToTextFile()           -> kml_to_csv()
convertColumnsToCSV()               -> txt_to_csv()
plotCenterline()                    -> plot_centerline()
plotCenterlineWidth()               -> plot_centerline_width()
riverWidthFromCenterline()          -> width()
saveCenterlineCSV()                 -> save_centerline_csv()
saveCenterlineMAT()                 -> save_centerline_mat()
kml_to_csv() extra arg              -> text_output_name (to be removed)
txt_to_csv() extra arg              -> text_file (to be removed)


Class and Variable Names:
riverCenterline                     -> CenterlineWidth
optional_cutoff extra arg           -> cutoff (to be removed)

Variables Names:
centerlineVoronoi                   -> centerline_voronoi
centerlineEqualDistance             -> centerline_equal_distance
centerlineEvenlySpaced              -> centerline_evenly_spaced
centerlineSmoothed                  -> centerline_smoothed
centerlineLength                    -> centerline_length
rightBankLength                     -> right_bank_length
leftBankLength                      -> left_bank_length
centerlineVoronoiRelative           -> centerline_voronoi_relative 
centerlineEqualDistanceRelative     -> centerline_equal_distance_relative
centerlineEvenlySpacedRelative      -> centerline_evenly_spaced_relative
centerlineSmoothedRelative          -> centerline_smoothed_relative
save_plot_name extra arg            -> save_plot (to be removed, plot_centerline, plot_centerline_width)

Additional work

Expanded codecov for new sinuosity functionality, deprecation, and future warnings

Bug fixes and README.md edits

Pytests: Tests for Python 3.10, 3.11, 3.12 against Ubuntu, macOS, Windows

1.7.0 - Sinuosity, Deprecation Warning

New functionality: Sinuosity

centerline-width now includes the ability to calculate the sinuosity. Sinuosity is a feature of rivers and can be indicative of meandering rivers

• sinuosity: the total sinuosity of the river
• incremental_sinuosity(): incremental sinuosity of the river at evenly spaced increments

Sinuosity = centerline length / straight distance from first/last point
Sinuosity = river length / straight line length of the river

Where sinuosity is broken in types:

SI < 1.05: Almost straight river
1.05 <= SI < 1.25: Winding river
1.25 <= SI < 1.5: Twisty river
1.5 <= Meandering river

Upcoming 2.0.0 Deprecation Warning

With the exception of any hot-fixes, the next release for centerline-width will be version 2.0.0. This will be a large overhaul of the package to better adhere to Pep8 Python Style best practices. This will include changes made to function and variable names. You will still be able to use the original function names, but they will now throw a DeprecationWarning and advise you to use the new function name. Eventually the old names will be deprecated and no longer usable.

All the README and documentation information will be changed to reflect the new names, but if there are any questions, feel free to submit it at the centerline-width/issues

Backwards Compatibility Conflicts

• riverArea renamed to area for better PEP 8 clarity (most will be covered in the 2.0.0 release)
• Distrubtion changed from setup.py to pyproject.toml

Bug fixes and README.md edits

Pytests: Tests for Python 3.10, 3.11, 3.12 against Ubuntu, macOS, Windows

1.6.0 - riverArea, account for curvature of Earth, flip_direction

Update to Back End for plotCenterlineWidth()

Update accounts for the curvature of the Earth when calculating the slope for width with plotCenterlineWidth()

Previously, slopes were calculated based on transect_span_distance without accounting for the curvature of the planet. Updated functionality now accounts for the curvature of the planet (defined by ellipsoid, defaults to WGS84). Adjusts positions where width lines intersect banks.

Previous (left) and updated (right) places where width lines intersect bank

Area of River

Return the area contained within the polygon generated the left and right bank latitude/longitudes

river_object.riverArea

Area returned in kilometers^2

import centerline_width
river_object = centerline_width.riverCenterline(csv_data="data/river_coords.csv")
river_area = river_object.riverArea

Code Coverage

New code coverage and testing to track back end of repo

Expanding pytests to coverage existing functionality for centerline and widths (~93%) error handling and expected outputs

Backwards Compatibility Conflicts

convertColumnsToCSV() argument flipBankDirection changed to flip_direction to be consistent with snake-case variable naming conventions among other functions

Drops active support for Python 3.9 in support of NEP 29

Bug fixes and README.md edits

Pytests: Tests for Python 3.10, 3.11, 3.12 against Ubuntu, macOS, Windows

1.5.0 - show_plot, Python 3.12 support, relative paths

New options: show_plot

New option show_plot and the option to use relative paths. New options are optional and backwards compatible, so there should be no impact on existing scripts.

show_plot

New option in plotCenterline() and plotCenterlineWidth()

New option to not show a newly generated plot. The plot will still save if save_plot is still in use. Useful when running centerline-width as part of a loop to save multiple plots without having to close each plot after it is generated. show_plot=False is the same as not using plt.show() in Matplotlib.

Relative Paths

New back-end option to use a relative instead of absolute path when convertColumnsToCSV()

relative path: file_path = "../../B/aaa.txt"
absolute path: file_path = "test/testing/B/aaa.txt"

Python 3.12 Support

Expanded testing suite and verify support with Python 3.12. Currently supporting Python 3.9, 3.10, 3.11, 3.12

Developer Environment

New conda environment file environment.yml for working with or testing against the centerline-width

Bug fixes and README.md edits

Pytests: 233 tests for Python 3.9, 3.10, 3.11, 3.12 against Ubuntu, macOS, Windows

1.4.1 - equal_axis, dark_mode, transect_slope

New Options: equal_axis, transect_slope, dark_mode

All new options are optional and backwards compatible so there should be no impact to existing scripts

equal_axis

Closes: #4 where perpendicular width lines do not appear perpendicular

equal_axis will set the x and y axis of the plot to be equal. Useful to show the perpendicular width lines as perpendicular since it can appear distorted by default in Matplotlib

equal_axis=False	equal_axis=True

transect_slope

The width lines are generated as perpendicular to the slopes of the points across transect_span_distance

By default, transect_slope="Average" where the width lines are perpendicular to the average slopes of the across span distance. For example: [A, B, C, D] = avg( slope([A, B]) + slope([B, C]) + slope([C+D]) )

Optionally, if transect_slope="Direct" then the width lines will be perpendicular to slope of the first and last point. For example: [A, B, C, D] = slope([A, D]) to avoid being susceptible to rapid small changes along the centerline

transect_slope="Average"	transect_slope="Direct"

dark_mode

New smart dark mode option when generating Matplotlib (for long suffering eyes)

dark_mode=False	dark_mode=True

Additional Changes:

• transect_span_distance minimum has been change from 3 to 2 (to measure a single slope)

Note: Re-release of 1.4.0 with hot fix for PyPi package

Bug fixes and README.md edits
Pytests: 229 tests for Python 3.9, 3.10, 3.11

1.3.0 - New option for riverWidthFromCenterlinen

New Option for riverWidthFromCenterline: coordinate_reference

New option for riverWidthFromCenterlinen() to reference a width line

• Two options: Centerline and Banks
• By default, coordinate_reference="Centerline" where width lines are referenced in respect to the centerline coordinate that it intersects
• New option, coordinate_reference="Banks" where width lines are referenced in respect to the right and left banks that it intersects (resolves: #1)
• No changes to existing behavior and function is backwards compatible

More details: riverWidthFromCenterline

Bug fix: centerlineLength()

Length was being calculated incorrectly as the pairs of coordinates being calculated were not correctly updating (A->B + A->C, fix: A->B + B->C)

Thanks to @mthaddon for identifying the bug and PR fix #2 🎉

Bug fixes and README.md edits

Pytests: 211 tests

1.2.1 - Save CSV fix, inclusive of all points

Bug Fix: riverWidthFromCenterline()

Fix allows for width from centerline to be saved to a csv

• Bug introduced when coordinate_type renamed to coordinate_unit
• Backend updated: new script saveOutput.py
• saveOutput.py: saveCenterlineCSV() and saveCenterlineMAT() moved to a separate script

Inclusive of all points

left_bank_relative_coordinates now inclusive for all points

• Includes the first point of the left bank to be a Relative Distance of (0,0)

Bug fixes and README.md edits

Pytests: 205 tests

1.2.0 - Coordinate Unit Rename, Width Dictionary Fix

coordinate_type renamed to coordinate_unit: "Relative Distance" vs. "Decimal Degrees"

Original argument renamed from coordinate_type to coordinate_unit

Change can impact backward functionality in:

• plotCenterline()
• plotCenterlineWidth()
• saveCenterlineCSV()
• saveCenterlineMAT()

Fix to riverWidthFromCenterline()

Returns accurate coordinates and width size when using coordinate_unit = "Relative Distance"

Bug fixes and README.md edits

Pytests: 205 tests

1.1.0 - Coordinate Type Options

New Coordinate Option: "Relative Distance" vs "Decimal Degrees"

New optional argument to designate which coordinate system to use: coordinate_type

Decimal Degrees: Default option that uses a latitude/longitude of each point

Relative Distance: New option that converts each point to a distance from the first point on the left bank

Function that accept new coordinate_type option:

• plotCenterline()
• plotCenterlineWidth()
• saveCenterlineCSV()
• saveCenterlineMAT()

New river class options:

• centerlineVoronoiRelative
• centerlineEqualDistanceRelative
• centerlineEvenlySpacedRelative
• centerlineSmoothedRelative
• left_bank_relative_coordinates
• right_bank_relative_coordinates
• bank_polygon_relative
• top_bank_relative
• bottom_bank_relative
• starting_node_relative
• ending_node_relative
• bank_voronoi_relative
• x_voronoi_ridge_point_relative
• y_voronoi_ridge_point_relative

Bug fixes and README.md edits

Pytests: 205 tests

1.0.1 - ZOrder Fix for Centerline, README edits

README.md edits and ZOrder for Centerline

Update README

• Instructions to Generate KML files from Google Earth Pro
• Details about the purpose and example images for equal_distance

ZOrder

• Fix ZOrder so centerline sits on top of the blue Voronoi paths (when display_all_possible_paths=True)
• Centerline sits on top of blue paths when centerline marker_type="Line" and marker_type="Scatter"
  

Bug fixes and README.md edits
Pytests: 180 test