Add tutorial for pygmt.config #482

hemmelig · 2020-06-20T20:01:08Z

Description of proposed changes

Initial pull request for a tutorial going over the basics of pygmt.config and it's use as a context manager.

Fixes #458

Preview: https://pygmt-git-configtutorial.gmt.vercel.app/tutorials/configuration.html

Reminders

Run make format and make check to make sure the code follows the style guide.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.

Add tutorial detailing how to add text annotations to PyGMT figures. Follows the style of the other tutorials available, showing how to use the currently available arguments in the binding to the underlying GMT program 'text'. Fixes GenericMappingTools#469

Add tutorial detailing how the pygmt.config class can be used to override GMT default parameters, both permanently (globally) or temporarily (locally). Follows the style of the other tutorials available. Fixes GenericMappingTools#458

examples/tutorials/text.py

hemmelig · 2020-06-20T20:05:22Z

I realise I must have branched off my text_tutorial branch rather than going back to master first - apologies! Should I remove the text tutorial and resubmit?

Also, one thing I was wondering is whether it's possible to return to the original set of defaults after they have been overwritten globally without restarting the kernel?

seisman · 2020-06-20T20:12:08Z

I realise I must have branched off my text_tutorial branch rather than going back to master first - apologies! Should I remove the text tutorial and resubmit?

You can directly remove the two text-tutorial files and remove the text.rst entry from doc/index.rst, and then commit directly to this branch. No need to resubmit a new PR.

Also, one thing I was wondering is whether it's possible to return to the original set of defaults after they have been overwritten globally without restarting the kernel?

Currently not. I believe it's a very useful feature. Please open an issue for it.

Remove pygmt.Figure.text tutorial from this particular pull request, leaving only the pygmt.config tutorial.

doc/index.rst

examples/tutorials/gmt-config.py

seisman · 2020-07-25T04:26:42Z

examples/tutorials/gmt-config.py

+pygmt.config(MAP_FRAME_TYPE="plain")
+pygmt.config(FORMAT_GEO_MAP="ddd.xx")


In GMT 6.1.0, each session can have a global gmt.conf file, and each figure can also have its own gmt.conf (see https://docs.generic-mapping-tools.org/6.1/cookbook/features.html#gmt-modern-mode-hierarchical-levels).

Now these two lines no longer works as we expected. They actually change the defaults of the figure above. To change the defaults of the current figure, we need to move these two lines after fig=pygmt.Figure().

So hierarchically one must do something like:

# Set global (session) configuration fig = pygmt.Figure() # This will change the current 'level' from session to figure # Set figure configuration etc

That makes sense, I'll fix this up (and finish the two PRs I've opened!)

How would one trigger the further levels mentioned in the GMT 6.1.0 documentation (subplot, panel, inset)?

Currently, subplot and inset are not implemented in PyGMT yet, but see #412 and #427.

Just opened up an issue for inset at #663, we can discuss over there. The subplot implementation at #427 is also ready for review 😄

I just read it! I'll have a look at it, thanks.

seisman · 2020-07-25T04:41:18Z

examples/tutorials/gmt-config.py

+# It is also possible to temporarily override the default parameters, which is a very
+# useful for limiting the scope of changes to a particular plot. :class:`pygmt.config` is


As explained above, no need to use the with statement to limit the scope of changes to a single figure, but it's still useful if we want to limit the changes to one or a few calls.

I still like the syntax of using a context manager. For me, it's far more intuitive/easy to see the scope of the changes being made than tracking the level based on Figure calls.

Yes, it works the same as the figure level configurations, just needs one more indentation. I'm OK with the example, but the main idea of the context manager is to mimic the command line parameter gmt basemap --PARAMETER=value, which only affect one single command. So perhaps we can keep this example, and add one more example.

seisman · 2020-09-19T17:45:14Z

@hemmelig Do you still have time working on this PR? These are all good examples for pygmt.config() and should be merged into the documentation.

seisman · 2020-10-21T16:15:39Z

Ping @hemmelig again to see if he still wants to work on this PR. I will try to finalize and merge it if there is no response in 7 days.

Co-authored-by: Dongdong Tian <[email protected]>

Update the config tutorial to: - Move the pygmt.config calls to after an instance of Figure has been created. - Demonstrate the use of pygmt.config as a context manager in two instances: firstly, to override the defaults for a single command (akin to the --PARAMETER=<val> method in GMT); secondly, to override the defaults for a sequence of commands.

Rename the pygmt.config tutorial from gmt-config to configuration (as, presumably, the GMT bit is implied!).

hemmelig · 2020-10-22T23:31:27Z

Pushed up changes required to address main comments.

examples/tutorials/configuration.py

Correct the list of frame types available and slightly adjust the final example to show the difference made when using pygmt.config as a context manager to override the default settings for a single command.

examples/tutorials/configuration.py

Co-authored-by: Dongdong Tian <[email protected]>

seisman · 2020-10-27T05:30:54Z

@weiji14 I think this PR is good to merge (except the conflict and the pending CI). Please give it a final review if you have time.

weiji14

@weiji14 I think this PR is good to merge (except the conflict and the pending CI). Please give it a final review if you have time.

Looks good, just some very minor suggestions. The merge conflict will be fun to resolve, does @hemmelig want to give it a go at https://github.com/GenericMappingTools/pygmt/pull/482/conflicts? If not, I can handle it 😄

Once this is completed, I think we can expand on the pygmt.config tutorial a bit more in a separate PR, maybe have separate sections for changing FONT_, COLOR_, MAP_, etc as listed in https://docs.generic-mapping-tools.org/latest/gmt.conf.html.

examples/tutorials/configuration.py

Co-authored-by: Wei Ji <[email protected]>

seisman · 2020-10-29T19:33:39Z

/format

hemmelig added 2 commits June 18, 2020 14:58

Add tutorial for pygmt.config

585ed8c

Add tutorial detailing how the pygmt.config class can be used to override GMT default parameters, both permanently (globally) or temporarily (locally). Follows the style of the other tutorials available. Fixes GenericMappingTools#458

vercel bot temporarily deployed to Preview June 20, 2020 20:01 Inactive

stickler-ci reviewed Jun 20, 2020

View reviewed changes

examples/tutorials/text.py Outdated Show resolved Hide resolved

examples/tutorials/text.py Outdated Show resolved Hide resolved

weiji14 added the documentation Improvements or additions to documentation label Jun 21, 2020

Remove pygmt.Figure.text tutorial

c0da05e

Remove pygmt.Figure.text tutorial from this particular pull request, leaving only the pygmt.config tutorial.

vercel bot temporarily deployed to Preview June 22, 2020 14:04 Inactive

hemmelig mentioned this pull request Jun 22, 2020

Resetting default GMT parameters - pygmt.config #486

Open

weiji14 mentioned this pull request Jul 21, 2020

adding set to figure #540

Closed

Merge branch 'master' into config_tutorial

968f551

vercel bot temporarily deployed to Preview July 25, 2020 03:28 Inactive

seisman reviewed Jul 25, 2020

View reviewed changes

weiji14 mentioned this pull request Sep 6, 2020

Release PyGMT 0.2.0 #587

Closed

11 tasks

Merge branch 'master' into config_tutorial

6ec06c1

vercel bot temporarily deployed to Preview September 26, 2020 21:45 Inactive

seisman mentioned this pull request Oct 15, 2020

Mark xarray shading test fail for GMT<=6.1.1 #649

Merged

5 tasks

Apply suggestions from code review

c709bbe

Co-authored-by: Dongdong Tian <[email protected]>

vercel bot temporarily deployed to Preview October 22, 2020 22:53 Inactive

hemmelig added 2 commits October 23, 2020 00:26

Rename config tutorial

b9d5c10

Rename the pygmt.config tutorial from gmt-config to configuration (as, presumably, the GMT bit is implied!).

vercel bot temporarily deployed to Preview October 22, 2020 23:30 Inactive

seisman reviewed Oct 23, 2020

View reviewed changes

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

seisman reviewed Oct 23, 2020

View reviewed changes

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

weiji14 mentioned this pull request Oct 24, 2020

Release PyGMT 0.2.1 #665

Closed

14 tasks

Make suggested changes from review

c225f19

Correct the list of frame types available and slightly adjust the final example to show the difference made when using pygmt.config as a context manager to override the default settings for a single command.

vercel bot temporarily deployed to Preview October 26, 2020 13:47 Inactive

seisman reviewed Oct 26, 2020

View reviewed changes

Apply suggestions from code review

175c2b4

Co-authored-by: Dongdong Tian <[email protected]>

vercel bot temporarily deployed to Preview October 26, 2020 21:05 Inactive

weiji14 reviewed Oct 27, 2020

View reviewed changes

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

examples/tutorials/configuration.py Outdated Show resolved Hide resolved

seisman added this to the 0.2.1 milestone Oct 27, 2020

Apply suggestions from code review

dce7ad8

Co-authored-by: Wei Ji <[email protected]>

vercel bot temporarily deployed to Preview October 28, 2020 22:47 Inactive

Merge branch 'master' into config_tutorial

154a719

vercel bot temporarily deployed to Preview October 29, 2020 19:32 Inactive

[format-command] fixes

f0cc82c

vercel bot temporarily deployed to Preview October 29, 2020 19:38 Inactive

seisman approved these changes Oct 29, 2020

View reviewed changes

seisman changed the title ~~Tutorial covering pygmt.config~~ Add tutorial for pygmt.config Oct 29, 2020

seisman merged commit 2c14fbd into GenericMappingTools:master Oct 29, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add tutorial for pygmt.config #482

Add tutorial for pygmt.config #482

hemmelig commented Jun 20, 2020 •

edited by seisman

Loading

hemmelig commented Jun 20, 2020 •

edited

Loading

seisman commented Jun 20, 2020

seisman Jul 25, 2020

hemmelig Jul 25, 2020

hemmelig Jul 25, 2020

seisman Jul 25, 2020

weiji14 Oct 22, 2020

hemmelig Oct 22, 2020

seisman Jul 25, 2020

hemmelig Jul 25, 2020

seisman Jul 25, 2020

seisman commented Sep 19, 2020

seisman commented Oct 21, 2020

hemmelig commented Oct 22, 2020

seisman commented Oct 27, 2020

weiji14 left a comment

seisman commented Oct 29, 2020

		pygmt.config(MAP_FRAME_TYPE="plain")
		pygmt.config(FORMAT_GEO_MAP="ddd.xx")

		# It is also possible to temporarily override the default parameters, which is a very
		# useful for limiting the scope of changes to a particular plot. :class:`pygmt.config` is

Add tutorial for pygmt.config #482

Add tutorial for pygmt.config #482

Conversation

hemmelig commented Jun 20, 2020 • edited by seisman Loading

hemmelig commented Jun 20, 2020 • edited Loading

seisman commented Jun 20, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seisman commented Sep 19, 2020

seisman commented Oct 21, 2020

hemmelig commented Oct 22, 2020

seisman commented Oct 27, 2020

weiji14 left a comment

Choose a reason for hiding this comment

seisman commented Oct 29, 2020

hemmelig commented Jun 20, 2020 •

edited by seisman

Loading

hemmelig commented Jun 20, 2020 •

edited

Loading