Skip to content

Commit 2b3fd4d

Browse files
authored
Feat/doc (#185)
* add words for jzfs * add research data management for doc * refactor readme
1 parent f6f5c7e commit 2b3fd4d

File tree

5 files changed

+83
-22
lines changed

5 files changed

+83
-22
lines changed

README.md

Lines changed: 83 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,82 @@
11

2-
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
3-
[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
4-
<!-- ALL-CONTRIBUTORS-BADGE:END -->
5-
---
6-
7-
# JZFS
8-
9-
#### 🚧 Current Status: Incubating - JZFS is not ready for production usage. The API is still evolving and documentation is lacking.
102

11-
JZFS is a version control filesystem based on Git protocol for data management and publication with a command line interface and a Python API. With JZFS, you can version control arbitrarily large data, share or consume data, record your data’s provenance, and work computationally reproducible.
12-
13-
## Current Status and Roadmap
3+
<p align="center">
4+
<picture>
5+
<source media="(prefers-color-scheme: light)" srcset="https://github.com/GitDataAI/jzfs/blob/main/docs/jzfs-logo-words.png?raw=true">
6+
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/GitDataAI/jzfs/blob/main/docs/jzfs-logo-words.png?raw=true">
7+
<img alt="JZFS Logo" src="https://github.com/GitDataAI/jzfs/blob/main/docs/jzfs-logo-words.png" width="400px">
8+
</picture>
9+
</p>
10+
11+
<h2 align="center">Git Based & Version Control & Joint Management <br/>for code, data, model and their relationship</h2>
12+
13+
> Delivers distributed data management system that keeps track of your data from code to PB scale dataset and ensures reproducibility.
14+
15+
<div align="center">
16+
<h3 align="center">
17+
<a href="https://gitdata.ai">JZFS Cloud</a> |
18+
<a href="https://gitdata.ai/">User Guide</a> |
19+
<a href="https://gitdata.ai/">API Docs</a> |
20+
<a href="https://github.com/GitDataAI/jzfs">Roadmap 2025</a>
21+
</h3>
22+
23+
<a href="https://github.com/GitDataAI/jzfs/releases/latest">
24+
<img src="https://img.shields.io/github/v/release/GitDataAI/jzfs.svg" alt="Version"/>
25+
</a>
26+
<a href="https://github.com/GitDataAI/jzfs/releases/latest">
27+
<img src="https://img.shields.io/github/release-date/GitDataAI/jzfs.svg" alt="Releases"/>
28+
</a>
29+
<a href="https://hub.docker.com/r/gitdatateam/jzfs/">
30+
<img src="https://img.shields.io/docker/pulls/gitdatateam/jzfs.svg" alt="Docker Pulls"/>
31+
</a>
32+
<a href="https://github.com/GitDataAI/jzfs/actions/workflows/flow.yml">
33+
<img src="https://github.com/GitDataAI/jzfs/actions/workflows/flow.yml/badge.svg" alt="GitHub Actions"/>
34+
</a>
35+
<a href="https://codecov.io/gh/GitDataAI/jzfs">
36+
<img src="https://codecov.io/gh/GitDataAI/jzfs/branch/main/graph/badge.svg?token=FITFDI3J3C" alt="Codecov"/>
37+
</a>
38+
<a href="https://github.com/GitDataAI/jzfs/blob/main/LICENSE">
39+
<img src="https://img.shields.io/github/license/GitDataAI/jzfs" alt="License"/>
40+
</a>
41+
42+
<br/>
43+
44+
<a href="https://gitdata.ai/slack">
45+
<img src="https://img.shields.io/badge/slack-GitDataAI-0abd59?logo=slack&style=for-the-badge" alt="Slack"/>
46+
</a>
47+
<a href="https://x.com/GitDataAI">
48+
<img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=for-the-badge" alt="Twitter"/>
49+
</a>
50+
<a href="https://www.linkedin.com/company/gitdataai">
51+
<img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=for-the-badge" alt="LinkedIn"/>
52+
</a>
53+
</div>
54+
55+
## Introduction
56+
57+
**JZFS** is an open-source, cloud-native version control filesystem based on Git protocol for data management and publication with a command line interface and a Python API. With JZFS, you can version control arbitrarily large data, share or consume data, record your data’s provenance, and work computationally reproducible.
58+
59+
JZFS adapts principles of open-source software development and distribution to address the technical challenges of data management, data sharing, and digital provenance collection across the life cycle of digital objects.
60+
61+
![](docs/jzfs-joint-management.png)
62+
63+
Compared with code in software development, data tend not to be as precisely
64+
identified because data versioning is rarely or only coarsely practiced. Scientific computation
65+
is not reproducible enough, because data provenance, the information of how a digital file
66+
came to be, is often incomplete and rarely automatically captured. Last but not least, in
67+
the absence of standardized data packages, there is no uniform way to declare actionable
68+
data dependencies and derivative relationships between inputs and outputs of a computation. JZFS aims to solve these issues by providing streamlined, transparent management
69+
of code, data, computing environments, and their relationship.
70+
71+
### Current Status and Roadmap
1472

1573
JZFS is still in the early development stages and is considered **incubating**. There is no commitment to ongoing maintenance or development. As the project evolves, this may change in the future. Therefore, we encourage you to explore, experiment, and contribute to JZFS, but do not attempt to use it in production.
1674

1775
The immediate next steps for the project are to fill obvious gaps, such as implementing error handling, removing panics throughout the codebase, supporting additional data types, and writing documentation. After that, development will be based on feedback and contributions.
1876

77+
JZFS's long-term goal is to build data ecosystems that enable new innovations.
78+
79+
1980
### Reserach Data Management
2081

2182
JZFS is based on Git with extend capabilities, especially with respect to managing large files.
@@ -31,7 +92,7 @@ JZFS is used to collect
3192
all experimental metadata about the complete timeline of longitudinal and multimodal animal experiments,
3293
including MRI, histology, electrophysiology, and behavior.
3394

34-
![](./docs/research-flow.png)
95+
![](./docs/jzfs-research-flow.png)
3596
Project planning and experimental details are recorded in an in-house relational cloud-based database.
3697

3798
A key element for both the database and the data storage is the
@@ -43,16 +104,12 @@ specific project is organized following the YODA principles (https://handbook.da
43104
In preparation for publication and to facilitate
44105
data reproducibility, the experimental raw and processed data is made publicly available on GitData.AI.
45106

46-
47107
JZFS is used as the central data management tool (Fig. above) and for version control: It keeps track of which
48108
files were modified, when, and by whom, and provides the ability to restore previous states. To this end, JZFS
49109
is agnostic of the data type and provides a unified interface for managing code and data files.
50110

51111

52-
#### joint management of code, data, and their relationship
53-
![](docs/jzfs-joint.png)
54-
55-
### Added value
112+
### DataHub
56113
Our central use case is the DataHub(Like Github, buf for Data),which essentially consists of a Git version control for data and a Git collaboration for data.
57114

58115
In the JZFS DataHub model, each node maintains a copy of the files and all of the history of each file.
@@ -63,9 +120,9 @@ Writes are organized on branches.
63120
Git is designed to compute differences between versions quickly.
64121
Generally, Git relies on human action to share and merge changes.
65122

66-
Fault tolerance and trustless-ness are achieved via the separation of remotes from individual nodes.
67-
Each node in the network is maintaining it's own copy, its history and coordinating via one or many remotes.
68-
If a remote you trust gets corrupted, you have the ability to roll back to a previous good state and switch to a new remote.
123+
Fault tolerance and trustless-ness are achieved via the separation of remotes from individual nodes.
124+
Each node in the network is maintaining it's own copy, its history and coordinating via one or many remotes.
125+
If a remote you trust gets corrupted, you have the ability to roll back to a previous good state and switch to a new remote.
69126
Even if you lose your copy you can rely on other nodes' copies to restore from.
70127

71128
This enables us to create transparency across internal and external data.
@@ -74,18 +131,22 @@ It forms the basis for a new way of practicing data exchange and contract design
74131

75132
It is crucial that data exchange works both within the company and in individually controllable data networks (data space).
76133

134+
### Data Space
77135
JZFS data space consists of so-called “DataHubs” like one or many remotes in Git, which are virtual data nodes for sharing data and building data networks.
78136
A single DataHub manages various data connections and can join together with other hubs to form a network through targeted synchronization.
79137
Based on data contracts mapped in the network, data can be released to other participants, enabling efficient data exchange.
80138

81139

82140
![](./docs/jzfs-space.png)
83141

84-
JZFS offers git for data technology for exchanging data in data hub and data space.
142+
JZFS offers git for data technology for exchanging data in data hub and data space.
143+
85144
The added value is clear: simple, transparent data management combined with intuitive linking and sharing of data in decentralized networks – data space.
86145
This enables secure, trustworthy data exchange across organizational boundaries.
87146

88-
JZFS's long-term goal is to build data ecosystems that enable new innovations.
147+
148+
149+
89150

90151
### Deploy
91152
```bash

docs/jzfs-joint-management.png

416 KB
Loading

docs/jzfs-logo-words.png

71.4 KB
Loading

docs/jzfs-logo.png

489 KB
Loading

docs/jzfs-research-flow.png

310 KB
Loading

0 commit comments

Comments
 (0)