Mizuna is a package that automates uploading visualizations to Overleaf projects (or git repositories).
Project description
Mizuna
Mizuna is a Python package meant to automate uploading graphs and visualizations (e.g., matplotlib, Seaborn) to Overleaf. In reality, it's a small wrapper to invoke a git add/commit/push to a repository on files of your choice.
Why?
Visualizations need constant iteration. I noticed I was spending ~10 seconds every time I navigated Overleaf's UI and recompiling LaTeX to upload and verify changes in my figures. Doing it programmatically improved my workflow by not navigating the UI every change.
The concept is a simplified version of the gigaleaf library without needing to use Gigantum for data analysis. This is a local solution that work directly with Overleaf (or any git repository).
Installation
Installation is done through PyPI:
$ pip install mizuna
How to Use
Quick Start
This is a brief example on initializing Mizuna, creating and saving a figure, tracking it, and syncing with the remote.
# Import Mizuna object
import seaborn as sns
import matplotlib.pyplot as plt
from mizuna import Mizuna
# Repository URL
remote = 'https://git.overleaf.com/thisisarandomproject'
# Directory to clone the remote into
repo_dir = 'CloneHere'
# Create Mizuna object
m = Mizuna(remote, repo_dir)
# Generate and save a chart (e.g., Seaborn, matplotlib, etc.)
x = [1, 2, 3, 4, 5]
y = [2, 4, 6, 8, 10]
sns.scatterplot(x=x, y=y)
plt.savefig('mychart.png', format='png')
# Track a file
m.track('mychart.png')
# Sync with repository
m.sync()
The Mizuna
Object
Initialize the Mizuna object with the repository URL, the name of the local directory to clone the remote into, and (optionally) whether the local directory is within a networked drive (e.g., a Z: drive or Google Drive File Stream).
If the drive is networked, pass True
into the networked_drive
parameter for Mizuna to work properly.
See Limitations.
remote = 'https://git.overleaf.com/thisisarandomproject' # Repository URL
repo_dir = 'CloneHere' # Directory to clone the remote into
m = Mizuna(remote, repo_dir) # Mizuna object
remote = 'https://git.overleaf.com/thisisarandomproject' # Repository URL
repo_dir = 'CloneHere' # Directory to clone the remote into
m = Mizuna(remote, repo_dir, networked_drive=True) # Mizuna object (networked drive)
Tracking
Mizuna can track a single file:
m.track('mychart.png') # Track one file
A single file renamed on the remote:
m.track('mychart.png', 'figure1.png') # Track one file and rename on remote
m.track('mychart.png', 'figures/figure1.png') # You can also place files inside directories on the remote
A list of files:
m.track(['mychart1.png', 'mychart2.png', 'mychart3.png']) # Track multiple files
Or a dictionary containing multiple files with their respective renames on the remote:
sync_files = { 'mychart1.png': 'figure1.png',
'mychart2.png': 'figure2.png' }
m.track(sync_files) # Track multiple files with their renames on remote
Untracking
If you need to untrack a file or all files:
m.untrack('mychart.png') # Untrack a single file
m.untrack_all() # Untrack all files
Checking Tracked Files
If you need to see all the files currently tracked by Mizuna:
m.file_track_list() # List all files tracked
Syncing
And finally, push to Overleaf (or your git repository) when ready:
m.sync() # Pulls changes, replaces changes with the tracked figures, and pushes
Limitations
- Files from networked drives (e.g., Z drive, Google Drive File Stream) may throw an incorrect SameFileError exception.
- See https://bugs.python.org/issue33935
- To circumvent this issue, pass
True
into thenetworked_drive
parameter in the Mizuna constructor- This prevents samefile checks from shutil.copy()
- Overleaf git URLs only work with Premium accounts.
- Referring a single user to Overleaf unlocks git URLs.
License
Usage is provided under the MIT License. See LICENSE for full details.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.