DOC/Gallery example "Scatter plot with histograms": General improvements

[yvonnefroehlich]

Description of proposed changes

This PR contains general improvements of the Gallery example "Scatter plot with histograms":

• Introduce / use a variable for xshift and yshift to make them more flexible (but maybe reduced readability?) Feedback is welcome (:
• Rewrap to 88 chars
• Improve / correct a few comments

Preview: https://pygmt-dev--3628.org.readthedocs.build/en/3628/gallery/histograms/scatter_and_histograms.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 wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

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

• /format: automatically format and lint the code

[michaelgrund]

Suggested change

	# Note that the y-axis annotations, ticks, and label "Counts" are shown in x-axis
	# Note that the y-axis ticks, tick labels, and axis label "Counts" are shown in x-axis

[yvonnefroehlich]

Hm. Strickly speaking there are no "tick labels" in GMT but it's called "annotations" 😬.

[michaelgrund]

You're right, but for me the sentence as it was did not describe the content satisfactory. Maybe @GenericMappingTools/pygmt-maintainers have an opinion on that?

[seisman]

For this histogram, the region is set to be region=[ymin, ymax, 0, 0], so the vertical axis is the actual X-axis and the horizontal axis is the actual "Y-axis". So, instead of saying:

Note that the y-axis annotations, ticks, and label "Counts" are shown in x-axis direction due to the rotation caused by horizontal=True.

Maybe we should say something like:

horizontal=True plots horizontal histograms, with X/Y axes flipped. I.e., the X axis is plotted vertically and the Y axis is plotted horizontally.

[yvonnefroehlich]

We probably also have to update the histogram tutorial at

pygmt/examples/tutorials/advanced/cartesian_histograms.py

Lines 82 to 85 in 8b6f61d

	# Use horizontal bars
	# Please note the flip of the x and y axes regarding annotations, ticks, gridlines,
	# and labels
	horizontal=True,

[seisman]

Updated at cead753.

[yvonnefroehlich]

Hm, maybe we also want to allow for non-squared scatter plots, to account for different wide values ranges of x and y?

width_scat, height_scat, height_histo = 4, 4, 5	width_scat, height_scat, height_histo = 4, 8, 5

[yvonnefroehlich]

Suggested change

	# Set plot size.
	# The scatter plot is 10x10, and the histograms are 10x3 and 3x10, respectively.
	width, height = 10, 3
	# Set the plot size
	# Here, the scatter plot is 4x8, and the histograms are 4x5 and 5x8, respectively
	width_scat, height_scat, height_histo = 4, 8, 5

[seisman]

For the two histograms, their widths are determined by the "height" and "weight" of the scatter plot, and their heights can be any values.

I feel we can just define the dimensions for the scatter plot only, and hardcode other dimensions in the projection parameter.

[seisman]

I've made the changes in 34c8568.

[michaelgrund]

Since it's just an example to show that it's possible to generate such plots with a few lines of extra code I would not overengineer at this point. If someone needs to adjust such plot for own purposes I guess it will be straightforward.

[seisman]

@yvonnefroehlich @michaelgrund In my opinion, this PR now is ready for merging. Please give this PR a final review.

[yvonnefroehlich]

Do we want to skip the unit? If we keep centimeters, we need to update a few other lines (an partly need f-strings).

Suggested change

	projection=f"X{width}/{height}",
	projection=f"X{width}c/{height}c",

[seisman]

I'm more inclined to skip the unit if possible. For projections, it's fine to keep the unit or not, but for other parameters, e.g, xshift, skipping the unit makes more sense (i.e., xshift=width + 2, rather than xshift=f"{width + 2}c.