Python Client Guide

The Electrospinning Data Python client is a production-ready library designed for researchers to interact programmatically with our dataset. It focuses on simplicity, reproducibility, and seamless integration with the Python data science stack (pandas).

---

Installation

Install the package via pip:

pip install electrospinning-data-client

[!NOTE] The package requires Python 3.8+ and depends on requests and pandas.

---

Quick Start

The quickest way to get started is using the top-level convenience functions.

import electrospinning_data_client as edc

# Download the latest dataset directly into a pandas DataFrame
df = edc.load_latest_dataset()

print(f"Retrieved {len(df)} records")
print(df.head())

---

Filtering Data

The client allows you to apply any of the supported API filters directly as a dictionary or using the fluent FilterBuilder for better type safety and readability.

Using FilterBuilder (Recommended)

The FilterBuilder provides an ergonomic way to construct complex queries.

from electrospinning_data_client import FilterBuilder, load_latest_dataset

# Find PAN produced with voltage between 20 and 30 kV
filters = (FilterBuilder()
           .polymer("PAN")
           .voltage(min_val=20, max_val=30)
           .build())

df = load_latest_dataset(filters=filters)

Using a Dictionary

import electrospinning_data_client as edc

# Direct dictionary usage
filters = {
    "polymer": "PAN",
    "voltageMin": 20,
    "voltageMax": 30
}

df = edc.load_latest_dataset(filters=filters)

Common Filter Keys

Feature	Filter Key	Description
Polymer	polymer	Case-insensitive polymer name (e.g., PAN, PVP)
Solvent	solvent	Case-insensitive solvent name (e.g., DMF)
Voltage	voltageMin / voltageMax	Voltage range in kV
Flow Rate	flowRateMin / flowRateMax	Flow rate range in mL/h
Distance	tipDistMin / tipDistMax	Tip-to-collector distance in cm

---

Versioned Downloads

For reproducible research, we recommend referencing specific dataset versions.

import electrospinning_data_client as edc

# 1. List available versions
client = edc.ElectrospinningDataClient()
versions = client.get_versions()
for v in versions:
    # Access attributes directly (snake_case)
    print(f"Version: {v.version_identifier}, Count: {v.record_count}")

# 2. Download a specific version
df_v1 = edc.load_versioned_dataset("v1.0.0")

---

API Reference

ElectrospinningDataClient

The core class for more advanced interactions.

__init__(base_url=None, timeout=60, verify=True)

Initialize the client. Defaults to the official production API. Uses connection pooling via requests.Session.

download_latest(filters=None)

• Returns: pandas.DataFrame
• Description: Fetches the latest release, applying optional filters. Columns are automatically flattened into research-ready names (e.g., experiment_id, polymer(s), solution_concentration).

download_version(version, filters=None)

• Returns: pandas.DataFrame
• Description: Fetches a specific version snapshot.

export_file(output_path, export_format='xlsx', version='latest', filters=None)

• Description: Downloads the dataset in a specified format (xlsx, json, zip) directly to a file.
• Example:

  client.export_file("data.xlsx", export_format="xlsx", filters={"polymer": "PAN"})

get_versions()

• Returns: List[VersionInfo]
• Description: Retrieves Metadata for all available version snapshots.

close()

• Description: Closes the underlying transport session. Can be used manually or via a context manager if using the client directly.

---

Working with Pandas

Once the data is in a DataFrame, you can leverage all of pandas' power for analysis. The client ensures that physical quantities are numeric and categorical data is standardized.

import electrospinning_data_client as edc
import matplotlib.pyplot as plt

df = edc.load_latest_dataset()

# The client uses idiomatic snake_case column names
pan_data = df[df['polymer(s)'] == 'PAN']

# Calculate average fiber diameter (numeric column)
avg_diameter = pan_data['fiber_diameter'].mean()
print(f"Average PAN Fiber Diameter: {avg_diameter:.2f} nm")

# Simple visualization
df.plot(kind='scatter', x='voltage', y='fiber_diameter')
plt.show()