Wrap fitcircle

[willschlitzer]

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]

Should support parameters x/y, too.

[seisman]

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]

@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]

@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]

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

1. 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),
}

2. Anyone who wants both (i.e., -L3) should call pygmt.fitcircle twice.
3. 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,
}

4. 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.