Wrap fitcircle by willschlitzer · Pull Request #1550 · GenericMappingTools/pygmt

willschlitzer · 2021-09-29T07:07:54Z

This pull request wraps the module fitcircle.

Preview at https://pygmt-dev--1550.org.readthedocs.build/en/1550/api/generated/pygmt.fitcircle.html

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

seisman · 2026-08-12T11:43:43Z

fitcircle has three important options:

-L: select the averaging method
-S: output small circle pole or not
-M: controls the output of columns

Their combinations can lead to quite different output formats, as shown below:

$ gmt fitcircle @sat_03.txt -L1
330.249933144   -18.4048179232  Points read: 703 Average Position (Flat Earth)
330.16910976    -18.4206421065  L1 Average Position (Fisher's Method)
52.7435567383   21.2080711967   L1 N Hemisphere Great Circle Pole (Cross-Averaged)
232.743556738   -21.2080711967  L1 S Hemisphere Great Circle Pole (Cross-Averaged)
$ gmt fitcircle @sat_03.txt -L2
330.249933144   -18.4048179232  Points read: 703 Average Position (Flat Earth)
330.169184777   -18.4206532702  L2 Average Position (Eigenval Method)
52.7451972868   21.2040074195   L2 N Hemisphere Great Circle Pole (Eigenval Method)
232.745197287   -21.2040074195  L2 S Hemisphere Great Circle Pole (Eigenval Method)
$ gmt fitcircle @sat_03.txt -L3
330.249933144   -18.4048179232  Points read: 703 Average Position (Flat Earth)
330.16910976    -18.4206421065  L1 Average Position (Fisher's Method)
52.7435567383   21.2080711967   L1 N Hemisphere Great Circle Pole (Cross-Averaged)
232.743556738   -21.2080711967  L1 S Hemisphere Great Circle Pole (Cross-Averaged)
330.169184777   -18.4206532702  L2 Average Position (Eigenval Method)
52.7451972868   21.2040074195   L2 N Hemisphere Great Circle Pole (Eigenval Method)
232.745197287   -21.2040074195  L2 S Hemisphere Great Circle Pole (Eigenval Method)
$ gmt fitcircle @sat_03.txt -L3 -S
330.249933144   -18.4048179232  Points read: 703 Average Position (Flat Earth)
330.16910976    -18.4206421065  L1 Average Position (Fisher's Method)
52.7435567383   21.2080711967   L1 N Hemisphere Great Circle Pole (Cross-Averaged)
232.743556738   -21.2080711967  L1 S Hemisphere Great Circle Pole (Cross-Averaged)
235.188595579   -22.0070525722  L1 Small Circle Pole. Distance from Pole to L1 Small Circle (degrees): 87.6019637313
330.169184777   -18.4206532702  L2 Average Position (Eigenval Method)
52.7451972868   21.2040074195   L2 N Hemisphere Great Circle Pole (Eigenval Method)
232.745197287   -21.2040074195  L2 S Hemisphere Great Circle Pole (Eigenval Method)
235.184676903   -22.0012240239  L2 Small Circle Pole.  Distance from Pole to L2 Small Circle (degrees): 87.6073161087
$ gmt fitcircle @sat_03.txt -L3 -F
330.249933144   -18.4048179232  330.16910976    -18.4206421065  52.7435567383   21.2080711967   232.743556738   -21.2080711967     330.169184777   -18.4206532702  52.7451972868   21.2040074195   232.745197287   -21.2040074195
$ gmt fitcircle @sat_03.txt -L3 -Ffmnsc -S
330.249933144   -18.4048179232  330.16910976    -18.4206421065  52.7435567383   21.2080711967   232.743556738   -21.2080711967     235.188595579   -22.0070525722  87.6019637313   330.169184777   -18.4206532702  52.7451972868   21.2040074195      232.745197287   -21.2040074195  235.184676903   -22.0012240239  87.6073161087
$ gmt fitcircle @sat_03.txt -L3 -Ff
330.249933144   -18.4048179232

The current implementation always returns a pandas.DataFrame object, which is not Pythonic, and also makes it difficult to implement the -F option later.

As mentioned in #1550 (comment), I propose

return a dictionary of tuples instead. The dictionary will look like the following for -L1/-L2:

solution = fitcircle(data="@sat_03.txt", norm=1)
>>> print(solution)
{
    "flat_mean": (330.249933144, -18.4048179232),
    "mean": (330.16910976, -18.4206421065),
    "north_pole": (52.7435567383, 21.2080711967),
    "south_pole": (232.743556738, -21.2080711967),
}

Anyone who wants both (i.e., -L3) should call pygmt.fitcircle twice.
When -S is used, the output can be:

{
    "flat_mean": (330.249933144, -18.4048179232),
    "mean": (330.16910976, -18.4206421065),
    "north_pole": (52.7435567383, 21.2080711967),
    "south_pole": (232.743556738, -21.2080711967),
    "small_circle_pole": (235.188595579, -22.0070525722),
    "small_circle_distance": 87.6019637313,
}

No need to implement the -F option, as the information is already in the dict. Anyone who wants the multi-column output can convert the dictionary manually.

Internally, we can just call fitcircle with -F and then extract the information to build the output dictionary.

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

seisman · 2026-08-21T10:13:03Z

        "@RidgeTest.prj",
        "@RidgeTest.shp",
        "@RidgeTest.shx",
+        "@sat_03.txt",


Please move this file to Line 130.

seisman · 2026-08-21T10:27:59Z

+    Setting ``norm`` to ``"absolutes"`` approximates the minimization of the
+    sum of absolute values of cosines of angular distances. This solution
+    finds the mean position as the Fisher average of the data, and the pole
+    position as the Fisher average of the cross-products between the mean
+    and the data. Averaging cross-products gives weight to points in
+    proportion to their distance from the mean, analogous to the "leverage"
+    of distant points in linear regression in the plane.
+
+    Setting ``norm`` to ``"squares"`` approximates the minimization of the
+    sum of squares of cosines of angular distances. It creates a 3 by 3
+    matrix of sums of squares of components of the data vectors. The
+    eigenvectors of this matrix give the mean and pole locations. This
+    method may be more subject to roundoff errors when there are thousands
+    of data. The pole is given by the eigenvector corresponding to the
+    smallest eigenvalue; it is the least-well represented factor in the data
+    and is not easily estimated by either method.


I'm re-reading the GMT documentation and feel that norm=1/norm=2 is more understandable than norm="absolutes"/norm="squares", assuming that most readers are already familiar with L1 and L2 norms. What do you think?

Truth be told, I don't know how fitcircle would be used practically and never used the GMT module (or remember why I chose to wrap it 5 years ago). I'll defer to your judgement; my thought is absolutes and squares is more Pythonic, but if you think 1/2 is more understandable to users, that's fine with me.

@seisman Any further thoughts on this?

I still feel that norm=1 and norm=2 is more understandable than "absolutes"/"squares".

seisman · 2026-08-21T10:28:48Z

+        - ``"small_circle_distance"``: the colatitude/distance in degrees
+          from the small circle pole to the small circle (a ``float``, not a
+          tuple)
+    """


See comment https://github.com/GenericMappingTools/pygmt/pull/1550/changes#r3829465312. Need to check if norm is 1 or 2.

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

seisman · 2026-09-07T02:21:59Z

+    Find mean position and great or small circle fit to points on sphere.
+
+    This method takes (longitude, latitude) values and converts them to Cartesian
+    three-vectors on the unit sphere. Then two locations are found: the mean
+    of the input positions, and the pole to the great circle which best fits
+    the input positions.
+
+    Setting ``norm`` to ``1`` (L1 norm) approximates the minimization of the
+    sum of absolute values of cosines of angular distances. This solution
+    finds the mean position as the Fisher average of the data, and the pole
+    position as the Fisher average of the cross-products between the mean
+    and the data. Averaging cross-products gives weight to points in
+    proportion to their distance from the mean, analogous to the "leverage"
+    of distant points in linear regression in the plane.
+
+    Setting ``norm`` to ``2`` (L2 norm) approximates the minimization of the
+    sum of squares of cosines of angular distances. It creates a 3 by 3
+    matrix of sums of squares of components of the data vectors. The
+    eigenvectors of this matrix give the mean and pole locations. This
+    method may be more subject to roundoff errors when there are thousands
+    of data. The pole is given by the eigenvector corresponding to the
+    smallest eigenvalue; it is the least-well represented factor in the data
+    and is not easily estimated by either method.
+
+    When the data are closely grouped along a great circle both solutions
+    are similar. If the data have large dispersion, the pole to the great
+    circle will be less well determined than the mean. Compare both
+    solutions as a qualitative check by calling :func:`pygmt.fitcircle`
+    twice, once for each ``norm``.


Please rewrap these lines to ~88 characters per line.

willschlitzer added 10 commits September 26, 2021 11:30

add fitcircle.py

7c1ae68

add fitcircle imports

41a3ded

add test_fitcircle

7e2dfee

add if statements and df column names

a239841

update formatting in fixture_data

d526eab

formatting

f02466e

add functions

0355a7d

add test info to test_fitcircle_no_outfile

9bf8331

add if statement for normalize

0360abc

add tests

1e86759

willschlitzer added the feature Brand new feature label Sep 29, 2021

willschlitzer added this to the 0.5.0 milestone Sep 29, 2021

willschlitzer self-assigned this Sep 29, 2021

willschlitzer modified the milestones: 0.5.0, 0.6.0 Oct 7, 2021

willschlitzer added 2 commits November 6, 2021 08:06

add fitcircle to index.rst

e5b7a91

run make format

3cde6d8

vercel Bot temporarily deployed to Preview November 6, 2021 08:07 Inactive

willschlitzer added 2 commits November 6, 2021 08:13

remove unused imports

c199d09

Merge branch 'main' into wrap/fitcircle

899a93f

vercel Bot temporarily deployed to Preview November 6, 2021 08:17 Inactive

willschlitzer added 2 commits November 6, 2021 08:19

change top docstring

d131d2f

Merge remote-tracking branch 'origin/wrap/fitcircle' into wrap/fitcircle

3e57da6

vercel Bot temporarily deployed to Preview November 6, 2021 08:27 Inactive

fix variable names

d4eebb7

vercel Bot temporarily deployed to Preview January 14, 2022 00:39 Inactive

Merge branch 'main' into wrap/fitcircle

913a70b

willschlitzer marked this pull request as ready for review January 14, 2022 00:40

vercel Bot temporarily deployed to Preview January 14, 2022 00:48 Inactive

weiji14 removed this from the 0.6.0 milestone Mar 13, 2022

willschlitzer added 3 commits August 13, 2026 22:41

Modify to return dictionary

6f0e501

Merge branch 'main' into wrap/fitcircle

0e196f8

Add typehint

eff642e

seisman reviewed Aug 14, 2026

View reviewed changes

Comment thread pygmt/src/fitcircle.py Outdated

seisman reviewed Aug 14, 2026

View reviewed changes

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

seisman reviewed Aug 14, 2026

View reviewed changes

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

willschlitzer and others added 10 commits August 14, 2026 15:49

Update pygmt/src/fitcircle.py

4cd6702

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Update pygmt/src/fitcircle.py

ff4c77c

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Update pygmt/src/fitcircle.py

3be5bac

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Merge branch 'main' into wrap/fitcircle

5fdfede

Update pygmt/src/fitcircle.py

a6777d8

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Update pygmt/src/fitcircle.py

6bd302a

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

remote outfile option from fitcircle

cdf4ef9

Update tests to remove testing for outfile

59afc1f

Add default value for norm

ec5deec

Update test_fitcircle to remove outfile and set default for norm

c0d0423

seisman reviewed Aug 15, 2026

View reviewed changes

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

Comment thread pygmt/src/fitcircle.py Outdated

willschlitzer and others added 5 commits August 15, 2026 17:55

Update pygmt/src/fitcircle.py

696a96d

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Update pygmt/src/fitcircle.py

5856e64

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Update pygmt/src/fitcircle.py

dd714ee

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Update pygmt/src/fitcircle.py

961ad92

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Formatting fix

efbe10d

seisman reviewed Aug 21, 2026

View reviewed changes

willschlitzer and others added 5 commits September 4, 2026 22:43

Update pygmt/src/fitcircle.py

73888a8

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Merge branch 'main' into wrap/fitcircle

26a75a0

move sat_03.txt in caching.py

32c2b83

Change norm parameters

2db9203

Merge branch 'main' into wrap/fitcircle

a6164b2

seisman reviewed Sep 7, 2026

View reviewed changes

Uh oh!

Conversation

willschlitzer commented Sep 29, 2021 • edited by weiji14 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seisman commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willschlitzer Sep 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

willschlitzer commented Sep 29, 2021 •

edited by weiji14

Loading

seisman commented Aug 12, 2026 •

edited

Loading

willschlitzer Sep 5, 2026 •

edited

Loading