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

willschlitzer · 2022-12-07T19:34:50Z

I don't think I'm able to come up with a good way to format the output; I'm going to close this PR for the time being. If anyone has a solution please feel free to reopen it!

seisman · 2022-12-09T03:28:19Z

I'm reopening the issue so it's more visible to people who'd like to help.

weiji14 · 2026-08-02T23:31:33Z

+    """
+    Load the sample data from the @sat_03 remote file.
+    """
+    fname = which("@sat_03.txt", download="c")


This @sat_03.txt file will need to be added to the cache list at https://github.com/GenericMappingTools/pygmt/blob/v0.19.0/pygmt/helpers/caching.py

weiji14 · 2026-08-02T23:43:22Z

+        return lib.virtualfile_to_dataset(
+            vfname=vouttbl,
+            output_type=output_type,
+            column_names=["longitude", "latitude", "method"],


These output columns might change depending on whether -L/norm=1/2 or -L/norm=3/True ? Could we do something like:

column_names=["longitude", "latitude", "method"] if kwargs.get("L") in {1, 2} else ["longitude_l1", "latitude_l1", "longitude_l2", "latitude_l2"],

or whatever column names make sense for norm=3.

Alternatively, we can just disable the ability to output to pandas format for norm=3/norm=True if it gets too complicated.

Decided to disable the pandas format for norm=3/True, as that seemed more straightforward.

seisman · 2026-08-04T12:32:52Z

+    S="small_circle",
+)
+def fitcircle(
+    data: PathLike | TableLike,


Should support parameters x/y, too.

seisman · 2026-08-04T12:40:48Z

+        $table_classes.
+    $output_type
+    $outfile
+    norm : int or bool


1, 2, 3 are not readable arguments. GMT recommends absolutes/squares/both instead.

https://github.com/GenericMappingTools/gmt/blob/d52a1e5825b73c3ad6948efce1ac8eeff01c2c93/src/longopt/fitcircle_inc.h#L32-33

As for the parameter, GMT supports norm and solution, while GMT.jl uses norm (https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/fitcircle.html).

seisman · 2026-08-06T09:38:52Z

@willschlitzer Could you please an issue for tracking this module, using the template at https://github.com/GenericMappingTools/pygmt/blob/main/.github/ISSUE_TEMPLATE/3-module_request.md

willschlitzer · 2026-08-12T11:10:38Z

@willschlitzer Could you please an issue for tracking this module, using the template at https://github.com/GenericMappingTools/pygmt/blob/main/.github/ISSUE_TEMPLATE/3-module_request.md

@seisman Done in #4821

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.

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 changed the title ~~Wrap fitcircle~~ WIP: Wrap fitcircle Dec 1, 2022

seisman marked this pull request as draft December 2, 2022 00:46

willschlitzer closed this Dec 7, 2022

seisman reopened this Dec 9, 2022

seisman modified the milestones: 0.8.0, 0.9.0 Dec 11, 2022

willschlitzer removed their assignment Feb 2, 2023

weiji14 removed this from the 0.9.0 milestone Mar 6, 2023

seisman added this to the 0.12.0 milestone Dec 11, 2023

seisman removed this from the 0.12.0 milestone Feb 26, 2024

willschlitzer added 2 commits August 1, 2026 21:47

Merge branch 'main' into wrap/fitcircle

bc1017a

Updates to fitcircle and test_fitcircle

ea1646d

willschlitzer changed the title ~~WIP: Wrap fitcircle~~ Wrap fitcircle Aug 2, 2026

willschlitzer self-assigned this Aug 2, 2026

willschlitzer added this to the 0.20.0 milestone Aug 2, 2026

willschlitzer marked this pull request as ready for review August 2, 2026 02:12

willschlitzer requested review from seisman and weiji14 August 2, 2026 04:06

weiji14 reviewed Aug 2, 2026

View reviewed changes

willschlitzer added 2 commits August 3, 2026 19:07

Add suggested fixes and test

8bcc2ff

Merge branch 'main' into wrap/fitcircle

68a12b0

seisman reviewed Aug 4, 2026

View reviewed changes

seisman added the needs review This PR has higher priority and needs review. label Aug 4, 2026

Make suggested changed for alias system and parameters

7cb916c

willschlitzer mentioned this pull request Aug 12, 2026

pygmt.fitcircle: Find mean position and great [or small] circle fit to points on sphere #4821

Open

19 tasks

Navigation Menu

Uh oh!

Wrap fitcircle - #1550

Wrap fitcircle#1550
willschlitzer wants to merge 40 commits into
mainfrom
wrap/fitcircle

willschlitzer commented Sep 29, 2021 •

edited by weiji14

Loading

Uh oh!

willschlitzer commented Dec 7, 2022

Uh oh!

seisman commented Dec 9, 2022

Uh oh!

weiji14 Aug 2, 2026

Uh oh!

weiji14 Aug 2, 2026 •

edited

Loading

Uh oh!

willschlitzer Aug 3, 2026

Uh oh!

Uh oh!

seisman Aug 4, 2026

Uh oh!

seisman Aug 4, 2026

Uh oh!

seisman commented Aug 6, 2026

Uh oh!

willschlitzer commented Aug 12, 2026

Uh oh!

seisman commented Aug 12, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

willschlitzer commented Dec 7, 2022

Uh oh!

seisman commented Dec 9, 2022

Uh oh!

weiji14 Aug 2, 2026

Choose a reason for hiding this comment

Uh oh!

weiji14 Aug 2, 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!

willschlitzer Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

seisman Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

seisman Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

seisman commented Aug 6, 2026

Uh oh!

willschlitzer commented Aug 12, 2026

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

willschlitzer commented Sep 29, 2021 •

edited by weiji14

Loading

weiji14 Aug 2, 2026 •

edited

Loading

seisman commented Aug 12, 2026 •

edited

Loading