Research Commands

The entrenar research command provides tools for academic research workflows, including artifact initialization, pre-registration, citation generation, and repository deposits.

Commands Overview

entrenar research <COMMAND>

Commands:
  init          Initialize a research artifact
  preregister   Create cryptographic pre-registration
  cite          Generate citation in various formats
  export        Export artifact metadata
  deposit       Deposit to repository (Zenodo/Figshare)
  bundle        Create RO-Crate package
  verify        Verify artifact integrity

init

Initialize a new research artifact with metadata.

entrenar research init [OPTIONS]

Options

OptionRequiredDescription
--id <ID>YesUnique artifact identifier
--title <TITLE>YesArtifact title
--type <TYPE>NoType: dataset, model, code, paper (default: dataset)
--author <AUTHOR>YesAuthor name (can specify multiple times)
--orcid <ORCID>NoAuthor ORCID (can specify multiple times)
--affiliation <AFF>NoAuthor affiliation (can specify multiple times)
--license <LICENSE>NoLicense: mit, apache2, cc0, cc-by, cc-by-sa, gpl3 (default: cc-by)
--description <DESC>NoArtifact description
--output <PATH>NoOutput file path (default: artifact.yaml)

Example

# Initialize a dataset artifact
entrenar research init \
  --id my-training-dataset \
  --title "ImageNet Subset for LoRA Training" \
  --type dataset \
  --author "Alice Smith" \
  --orcid "0000-0001-2345-6789" \
  --affiliation "Stanford University" \
  --license cc-by \
  --description "A curated subset of ImageNet for efficient LoRA fine-tuning experiments"

# Initialize a model artifact
entrenar research init \
  --id llama-lora-adapter \
  --title "LLaMA LoRA Adapter for Code Generation" \
  --type model \
  --author "Bob Jones" \
  --author "Carol White" \
  --output model-artifact.yaml

preregister

Create a cryptographically signed pre-registration for reproducibility.

entrenar research preregister [OPTIONS] <ARTIFACT>

Arguments

ArgumentDescription
<ARTIFACT>Path to artifact YAML file

Options

OptionDescription
--hypothesis <TEXT>Pre-registered hypothesis
--methods <TEXT>Pre-registered methods
--output <PATH>Output file path

Example

# Create pre-registration with hypothesis
entrenar research preregister artifact.yaml \
  --hypothesis "LoRA rank 64 will achieve equivalent accuracy to full fine-tuning" \
  --methods "Train on 10K samples with AdamW, lr=1e-4, 3 epochs" \
  --output preregistration.yaml

The pre-registration includes:

  • Git commit hash for reproducibility
  • Ed25519 cryptographic signature
  • Timestamp proof
  • Hypothesis and methods locked at registration time

cite

Generate citations in various academic formats.

entrenar research cite [OPTIONS] <ARTIFACT>

Arguments

ArgumentDescription
<ARTIFACT>Path to artifact YAML file

Options

OptionDescription
--format <FORMAT>Citation format: bibtex, apa, mla, chicago (default: bibtex)
--year <YEAR>Publication year (default: current year)

Example

# Generate BibTeX citation
entrenar research cite artifact.yaml --format bibtex --year 2024

# Output:
# @misc{my-training-dataset,
#   author = {Alice Smith},
#   title = {ImageNet Subset for LoRA Training},
#   year = {2024},
#   howpublished = {\url{https://example.com/artifact}}
# }

# Generate APA citation
entrenar research cite artifact.yaml --format apa --year 2024

# Generate MLA citation
entrenar research cite artifact.yaml --format mla

export

Export artifact metadata to different formats.

entrenar research export [OPTIONS] <ARTIFACT>

Arguments

ArgumentDescription
<ARTIFACT>Path to artifact YAML file

Options

OptionDescription
--format <FORMAT>Export format: json, yaml, datacite, schema-org (default: json)
--output <PATH>Output file path

Example

# Export as JSON
entrenar research export artifact.yaml --format json --output metadata.json

# Export as DataCite XML
entrenar research export artifact.yaml --format datacite --output datacite.xml

# Export as Schema.org JSON-LD
entrenar research export artifact.yaml --format schema-org --output schema.jsonld

deposit

Deposit artifact to a repository (Zenodo or Figshare).

entrenar research deposit [OPTIONS] <ARTIFACT>

Arguments

ArgumentDescription
<ARTIFACT>Path to artifact YAML file

Options

OptionDescription
--provider <PROVIDER>Repository: zenodo, figshare (default: zenodo)
--sandboxUse sandbox/test environment
--publishPublish immediately (otherwise draft)

Environment Variables

VariableDescription
ZENODO_TOKENAPI token for Zenodo
FIGSHARE_TOKENAPI token for Figshare

Example

# Deposit to Zenodo sandbox (for testing)
export ZENODO_TOKEN="your-api-token"
entrenar research deposit artifact.yaml --provider zenodo --sandbox

# Deposit and publish to Figshare
export FIGSHARE_TOKEN="your-api-token"
entrenar research deposit artifact.yaml --provider figshare --publish

bundle

Create an RO-Crate package for FAIR data sharing.

entrenar research bundle [OPTIONS] <ARTIFACT>

Arguments

ArgumentDescription
<ARTIFACT>Path to artifact YAML file

Options

OptionDescription
--output <PATH>Output directory (default: ./ro-crate)
--zipCreate ZIP archive

Example

# Create RO-Crate directory
entrenar research bundle artifact.yaml --output ./my-crate

# Create ZIP archive
entrenar research bundle artifact.yaml --output ./package --zip

The RO-Crate bundle includes:

  • ro-crate-metadata.json - JSON-LD metadata
  • All referenced data files
  • README with citation information
  • License file

verify

Verify artifact integrity and signatures.

entrenar research verify [OPTIONS] <ARTIFACT>

Arguments

ArgumentDescription
<ARTIFACT>Path to artifact YAML file

Options

OptionDescription
--deepPerform deep verification (check all referenced files)

Example

# Quick verification
entrenar research verify artifact.yaml

# Deep verification with file checksums
entrenar research verify artifact.yaml --deep

Verification checks:

  • YAML schema validity
  • Required metadata fields
  • Pre-registration signatures (if present)
  • File checksums (with --deep)
  • Git commit existence (if timestamp proof present)

Workflow Example

Complete research artifact workflow:

# 1. Initialize artifact
entrenar research init \
  --id experiment-2024 \
  --title "Temperature Scaling Ablation Study" \
  --type dataset \
  --author "Research Team" \
  --license cc-by

# 2. Pre-register hypothesis before running experiment
entrenar research preregister artifact.yaml \
  --hypothesis "T=4.0 is optimal for knowledge distillation" \
  --methods "Grid search T in [1.0, 8.0], step 0.5"

# 3. Run experiment (using entrenar-bench)
entrenar-bench temperature --start 1.0 --end 8.0 --step 0.5

# 4. Generate citation for paper
entrenar research cite artifact.yaml --format bibtex --year 2024

# 5. Create RO-Crate package
entrenar research bundle artifact.yaml --zip

# 6. Deposit to Zenodo
entrenar research deposit artifact.yaml --provider zenodo --publish

# 7. Verify final artifact
entrenar research verify artifact.yaml --deep

See Also