docs: add English documentation files

Author: RicardoRyn

docs/en/api/index.md

@@ -0,0 +1,17 @@
+# API
+
+::: plotfig.single_bar
+
+::: plotfig.multi_bars
+
+::: plotfig.correlation
+
+::: plotfig.matrix
+
+::: plotfig.brain_surface
+
+::: plotfig.circos
+
+::: plotfig.brain_connection
+
+::: plotfig.utils

docs/en/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+
+Automatically updated!

docs/en/index.md

@@ -0,0 +1,30 @@
+# Introduction
+
+`plotfig` is a Python library designed specifically for scientific data visualization, dedicated to providing efficient, easy-to-use, and beautiful plotting tools for cognitive neuroscience researchers.
+This project is developed based on mainstream visualization libraries in the industry—`matplotlib`, `surfplot`, and `plotly`, integrating their powerful features to meet the complex plotting needs in neuroscience and brain connectomics across various scenarios.
+
+![plotfig](../assets/plotfig.png)
+
+## Project Structure
+
+The project adopts a modular design, containing the following main functional modules:
+
+- `bar.py`: Bar chart plotting, suitable for comparative display of grouped data.
+- `matrix.py`: General matrix visualization, supporting multiple color schemes and annotation methods.
+- `correlation.py`: Correlation matrix visualization, facilitating analysis of correlation distributions between variables.
+- `circos.py`: Circos plot visualization, suitable for planar display of connections between brain regions.
+- `brain_surface.py`: Brain surface visualization, enabling plotting of 3D brain surface atlas structures.
+- `brain_connection.py`: Glass brain connectivity visualization, supporting complex brain network structure display.
+
+## Features
+
+- The `plotfig` API has a simple design with flexible parameters, making it suitable for researchers and data analysts to quickly integrate into their data analysis workflows.
+- Its modular architecture facilitates future feature expansion and custom development.
+- Combined with `matplotlib`, it supports vector graphics, high-resolution bitmap, and interactive HTML output, suitable for paper publication and academic presentation.
+
+---
+
+Fun fact: All elements of a figure[^1].
+![Parts of a Figure](https://matplotlib.org/stable/_images/anatomy.png)
+
+[^1]: [Quick start guide of matplotlib.](https://matplotlib.org/stable/tutorials/introductory/usage.html#parts-of-a-figure)

docs/en/installation.md

@@ -0,0 +1,84 @@
+# Installation
+
+`plotfig` supports installation via package managers or directly from source, requiring Python 3.11 or higher.
+
+## Install via Package Manager (Recommended)
+
+=== "uv"
+
+    ```bash
+    uv add plotfig
+    ```
+
+=== "pip"
+
+    ```bash
+    pip install plotfig
+    ```
+
+## Install from Source
+
+First, download the source code to a directory (e.g., `/path/to/plotfig`):
+
+```bash
+git clone https://github.com/RicardoRyn/plotfig.git /path/to/plotfig
+```
+
+Then execute the following in your project directory:
+
+=== "uv"
+
+    ```bash
+    uv add /path/to/plotfig
+    ```
+
+=== "pip"
+
+    ```bash
+    pip install /path/to/plotfig
+    ```
+
+!!! info
+
+    `/path/to/plotfig` should be replaced with the actual path.
+
+## Contributing
+
+If you wish to experience these features or participate in `plotfig` development, you can choose to install the project in editable mode.
+
+This installation mode allows your modifications to the local source code to take effect immediately, making it very suitable for debugging, development, and contributing code.
+
+Recommended workflow:
+
+1. Fork this repository to your GitHub account
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/USERNAME/plotfig.git /path/to/plotfig
+   ```
+3. Install in editable mode in your project directory:
+
+=== "uv"
+
+    ```bash
+    uv add --editable /path/to/plotfig
+    ```
+
+=== "pip"
+
+    ```bash
+    pip install -e /path/to/plotfig
+    ```
+
+!!! info
+
+    `/path/to/plotfig` should be replaced with the actual path.
+
+---
+
+**We welcome Issues and PRs!**
+
+Whether it's bug reports, feature suggestions, or documentation improvements.
+
+Feel free to open an [Issue](https://github.com/RicardoRyn/plotfig/issues).
+
+You can also submit a [PR](https://github.com/RicardoRyn/plotfig/pulls) directly to help us grow stronger 💪!

docs/en/usage/brain_connectivity.md

@@ -0,0 +1,70 @@
+# Brain Connectivity Plot
+
+Transparent brain plot that can display connectivity relationships between brain regions.
+You need to prepare surface files for left and right hemispheres, brain region-related nii.gz files, and a connectivity matrix.
+
+## Quick Plot
+
+For all parameters, see the API documentation for [`plot_brain_connection_figure`](../api/#plotfig.brain_connection.plot_brain_connection_figure).
+
+```python
+from plotfig import plot_brain_connection_figure, gen_symmetric_matrix
+
+# Generate random connectivity matrix
+connectome = gen_symmetric_matrix(31, sparsity=0.1, seed=42)
+
+# Left and right brain surface files and network node files need to be provided by yourself
+lh_surfgii_file = r"example_data/103818.L.midthickness.32k_fs_LR.surf.gii"
+rh_surfgii_file = r"example_data/103818.R.midthickness.32k_fs_LR.surf.gii"
+niigz_file = r"example_data/network.nii.gz"
+
+# HTML file output location
+output_file = "example_data/brain_connection.html"
+
+fig = plot_brain_connection_figure(
+    connectome,
+    lh_surfgii_file=lh_surfgii_file,
+    rh_surfgii_file=rh_surfgii_file,
+    niigz_file=niigz_file,
+    output_file=output_file,
+    scale_method="width",
+    line_width=10,
+    nodes_name=[f"ROI_{i}" for i in range(connectome.shape[0])],
+)
+```
+
+## Result Display
+
+![output](brain_connectivity_files/output.gif)
+
+The HTML file can be interactively viewed in a browser. You can manually take screenshots, or use the following command to batch generate multi-view images.
+
+```python
+from pathlib import Path
+from plotfig import save_brain_connection_frames
+
+# Create new folder to save frame images
+Path(f"./example_data/brain_connection_figures").mkdir(parents=True, exist_ok=True)
+save_brain_connection_frames(
+    fig,
+    output_dir=rf"./example_data/brain_connection_figures",
+    n_frames=36
+)
+```
+
+    100%|██████████| 36/36 [01:55<00:00,  3.19s/it]
+    2025-11-24 11:02:55.867 | INFO     | plotfig.brain_connection:save_brain_connection_frames:323 - Saved 36 images in ./example_data/brain_connection_figures
+
+plotfig provides a utility function to combine image sequences into GIF animations.
+
+```python
+from pathlib import Path
+from plotfig import create_gif_from_images
+
+create_gif_from_images(
+    Path("example_data/brain_connection_figures"),
+    output_name="output.gif"
+)
+```
+
+    2025-11-24 11:07:46.885 | INFO     | plotfig.brain_connection:create_gif_from_images:417 - GIF saved to: example_data\brain_connection_figures\outpug.gif

docs/en/usage/brain_connectivity_files/output.gif

@@ -0,0 +1,161 @@
+# Brain Surface Plot
+
+Brain surface plot is a chart used to visualize numerical data on the cerebral cortex surface.
+It can map values of different brain regions to corresponding areas of the cerebral cortex and display the distribution of these values in a color-coded manner.
+This type of chart is commonly used to display various brain region metrics in neuroscience research, such as BOLD signal intensity, myelination degree, volume or thickness, or other quantifiable brain features.
+
+The `plot_brain_surface_figure` function is developed based on the `surfplot` library, providing a unified and simplified interface for plotting brain surface maps for human, macaque, and chimpanzee brains.
+Currently supports multiple brain atlases including:
+
+1. Human Glasser (HCP-MMP) atlas[^1]. [Atlas CSV file](../assets/atlas_csv/human_glasser.csv).
+1. Human BNA atlas[^2]. [Atlas CSV file](../assets/atlas_csv/human_bna.csv).
+1. Chimpanzee BNA atlas[^3]. [Atlas CSV file](../assets/atlas_csv/chimpanzee_bna.csv).
+1. Macaque CHARM 5-level[^4]. [Atlas CSV file](../assets/atlas_csv/macaque_charm5.csv).
+1. Macaque CHARM 6-level[^4]. [Atlas CSV file](../assets/atlas_csv/macaque_charm6.csv).
+1. Macaque BNA atlas[^5]. [Atlas CSV file](../assets/atlas_csv/macaque_bna.csv).
+1. Macaque D99 atlas[^6]. [Atlas CSV file](../assets/atlas_csv/macaque_d99.csv).
+
+[^1]:
+    Glasser, M. F., Coalson, T. S., Robinson, E. C., Hacker, C. D., Harwell, J., Yacoub, E., Ugurbil, K., Andersson, J., Beckmann, C. F., Jenkinson, M., Smith, S. M., & Van Essen, D. C. (2016). A multi-modal parcellation of human cerebral cortex. Nature, 536(7615), Article 7615. https://doi.org/10.1038/nature18933
+[^2]:
+    Fan, L., Li, H., Zhuo, J., Zhang, Y., Wang, J., Chen, L., Yang, Z., Chu, C., Xie, S., Laird, A. R., Fox, P. T., Eickhoff, S. B., Yu, C., & Jiang, T. (2016). The Human Brainnetome Atlas: A New Brain Atlas Based on Connectional Architecture. Cerebral Cortex (New York, N.Y.: 1991), 26(8), 3508–3526. https://doi.org/10.1093/cercor/bhw157
+[^3]:
+    Wang, Y., Cheng, L., Li, D., Lu, Y., Wang, C., Wang, Y., Gao, C., Wang, H., Erichsen, C. T., Vanduffel, W., Hopkins, W. D., Sherwood, C. C., Jiang, T., Chu, C., & Fan, L. (2025). The Chimpanzee Brainnetome Atlas reveals distinct connectivity and gene expression profiles relative to humans. The Innovation, 0(0). https://doi.org/10.1016/j.xinn.2024.100755
+[^4]:
+    Jung, B., Taylor, P. A., Seidlitz, J., Sponheim, C., Perkins, P., Ungerleider, L. G., Glen, D., & Messinger, A. (2021). A comprehensive macaque fMRI pipeline and hierarchical atlas. NeuroImage, 235, 117997. https://doi.org/10.1016/j.neuroimage.2021.117997
+[^5]:
+    Lu, Y., Cui, Y., Cao, L., Dong, Z., Cheng, L., Wu, W., Wang, C., Liu, X., Liu, Y., Zhang, B., Li, D., Zhao, B., Wang, H., Li, K., Ma, L., Shi, W., Li, W., Ma, Y., Du, Z., … Jiang, T. (2024). Macaque Brainnetome Atlas: A multifaceted brain map with parcellation, connection, and histology. Science Bulletin, 69(14), 2241–2259. https://doi.org/10.1016/j.scib.2024.03.031
+[^6]:
+    Reveley, C., Gruslys, A., Ye, F. Q., Glen, D., Samaha, J., E. Russ, B., Saad, Z., K. Seth, A., Leopold, D. A., & Saleem, K. S. (2017). Three-Dimensional Digital Template Atlas of the Macaque Brain. Cerebral Cortex, 27(9), 4463–4477. https://doi.org/10.1093/cercor/bhw248
+
+## Quick Plot
+
+!!! info
+    Please ensure brain region names are correct before plotting.
+
+```python
+from plotfig import plot_brain_surface_figure
+
+data = {"lh_V1": 1, "rh_MT": 1.5}
+
+ax = plot_brain_surface_figure(data, species="human", atlas="glasser")
+```
+
+![png](brain_surface_files/brain_surface_4_0.png)
+
+```python
+from plotfig import plot_brain_surface_figure
+import matplotlib.pyplot as plt
+
+macaque_data = {"lh_V1": 1}
+chimpanzee_data = {"lh_MVOcC.rv": 1}
+
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 5))
+
+ax1 = plot_brain_surface_figure(
+    chimpanzee_data, species="chimpanzee", atlas="bna", ax=ax1, title_name="Chimpanzee"
+)
+ax2 = plot_brain_surface_figure(
+    macaque_data, species="macaque", atlas="charm5", ax=ax2, title_name="Macaque"
+)
+```
+
+![png](brain_surface_files/brain_surface_5_0.png)
+
+## Different Surface Files
+
+For humans, the following surface files are provided:
+
+1. `veryinflated`
+2. `inflated`
+3. `midthiickness`
+4. `sphere`
+5. `flat`
+
+```python
+from plotfig import plot_brain_surface_figure
+import matplotlib.pyplot as plt
+
+fig, axes = plt.subplots(2, 3, figsize=(12, 6))
+fig.delaxes(axes[1, 2])
+
+plot_data = {"lh_V1": 1, "rh_FST": 2}
+
+ax1 = plot_brain_surface_figure(plot_data, surf="veryinflated", ax=axes[0,0], title_name="veryinflated")
+ax2 = plot_brain_surface_figure(plot_data, surf="inflated", ax=axes[0,1], title_name="inflated")
+ax3 = plot_brain_surface_figure(plot_data, surf="midthickness", ax=axes[0, 2], title_name="midthickness")
+ax4 = plot_brain_surface_figure(plot_data, surf="sphere", ax=axes[1,0], title_name="sphere")
+ax5 = plot_brain_surface_figure(plot_data, surf="flat", ax=axes[1,1], title_name="flat")
+```
+
+![png](brain_surface_files/brain_surface_8_0.png)
+
+For chimpanzees, the following surface files are provided:
+
+1. `veryinflated`
+2. `midthiickness`
+
+```python
+from plotfig import plot_brain_surface_figure
+import matplotlib.pyplot as plt
+
+fig, axes = plt.subplots(1, 2)
+
+plot_data = {"lh_MVOcC.rd": 1, "rh_STG.r": 2}
+
+ax1 = plot_brain_surface_figure(plot_data, species="chimpanzee", atlas="bna", surf="veryinflated", ax=axes[0], title_name="veryinflated")
+ax3 = plot_brain_surface_figure(plot_data, species="chimpanzee", atlas="bna", surf="midthickness", ax=axes[1], title_name="midthickness")
+```
+
+![png](brain_surface_files/brain_surface_10_0.png)
+
+For macaques, the following surface files are provided:
+
+1. `veryinflated`
+2. `inflated`
+4. `pial`
+3. `midthiickness`
+5. `white`
+6. `flat`
+
+```python
+from plotfig import plot_brain_surface_figure
+import matplotlib.pyplot as plt
+
+fig, axes = plt.subplots(2, 3, figsize=(12, 6))
+
+plot_data = {"lh_V1": 1, "rh_FST": 2}
+
+ax1 = plot_brain_surface_figure(plot_data, species="macaque", atlas="charm5", surf="veryinflated", ax=axes[0,0], title_name="veryinflated")
+ax2 = plot_brain_surface_figure(plot_data, species="macaque", atlas="charm5", surf="inflated", ax=axes[0,1], title_name="inflated")
+ax3 = plot_brain_surface_figure(plot_data, species="macaque", atlas="charm5", surf="pial", ax=axes[0, 2], title_name="pial")
+ax4 = plot_brain_surface_figure(plot_data, species="macaque", atlas="charm5", surf="midthickness", ax=axes[1,0], title_name="midthickness")
+ax5 = plot_brain_surface_figure(plot_data, species="macaque", atlas="charm5", surf="white", ax=axes[1,1], title_name="white")
+ax6 = plot_brain_surface_figure(plot_data, species="macaque", atlas="charm5", surf="flat", ax=axes[1,2], title_name="flat")
+```
+
+![png](brain_surface_files/brain_surface_12_0.png)
+
+## More Settings
+
+For all parameters, see the API documentation for [`plot_brain_surface_figure`](../api/#plotfig.brain_surface.plot_brain_surface_figure).
+
+```python
+from plotfig import plot_brain_surface_figure
+
+data = {"lh_V1": 1, "rh_MT": 1.5, "rh_V1": -1}
+
+ax = plot_brain_surface_figure(
+    data,
+    species="human",
+    atlas="glasser",
+    surf="inflated",
+    cmap="bwr",
+    vmin=-1,
+    vmax=1,
+    colorbar=True,
+    colorbar_label_name="AAA"
+)
+```
+
+![png](brain_surface_files/brain_surface_15_0.png)